プチコン3号&BIGまとめWiki

Toukou/プチコンシリーズ共通音楽パックフォーマット NMPACKS の変更点


#title(投稿プログラム : プチコンシリーズ共通音楽パックフォーマット NMPACKS)
#contents
// ↑↑↑↑ この2行は削除しないでください。 ↑↑↑↑
//
// ←このように「//」で始まる行はコメントです。ページ本文には反映されません。
//------------------------------------------------------------------------------
// ・投稿年月日は、このページを投稿しようとしている今日の日付を半角数字で入力してください。
//   この日付は、投稿プログラムを自動的に年月日順に並べる際に使用されます。
// ↓↓↓
2019年5月26日投稿
// ↑↑↑
// ・作品をバージョンアップ (公開キーをアップデート) した際は、以下に更新日を記入し、
//   頭の「//」2文字を取り除くと「アップデート順」で上位に表示されます。
// ↓↓↓   (ページの内容だけ更新はページ更新日が自動的に記録されますので、対象外です)
/ 2019年7月8日更新
// ↑↑↑
//------------------------------------------------------------------------------
// ・投稿者名は、投稿プログラム一覧に表示するために使用します。
// ・「名無しさん」のままにしておくと、匿名の方からの投稿として扱われます。
// ↓↓↓
/ 投稿者 : 高原のな
// ↑↑↑
//------------------------------------------------------------------------------
// ・適当にタグをつけることができます。半角のコンマ区切りで複数つけられます。
//   タグをつけると、同じタグが付いたページを検索することができます。
// ★次に該当するプログラムは、特定のタグを設定するようご協力お願いします。
//   これらを設定すると、将来的に投稿プログラム一覧に目立つマークが付くようになる予定です。
// ・短いプログラム → 「1行プログラム」「数行プログラム」「1画面プログラム」タグのいずれか1つ
// ・該当するなら「ゲーム」「実用ツール」「音楽」タグのいずれか
// ↓↓↓
/ &tag(投稿プログラム,実用ツール,音楽);
// ↑↑↑

//------------------------------------------------------------------------------
// ここに概要とか書きます。
// ・** や *** で始まる行は子見出しとなります。* の数で深さが決まります。
// ・[#英数字] はページ内リンクに使用されるキーワードとなりますが、
//   消してもかまいません。ない場合はランダムな文字列が自動付与されます。
//   逆に、[#英数字] して同じものを増やしてしまった場合、目次からのリンクがちょっとおかしくなります。

* 概要 [#Summary]
プチコン3号/BIG/4とPiStarterで共通して使える、音楽パックフォーマットです。[[プチコン4完全対応版>4:Toukou/プチコンシリーズ共通音楽パックフォーマット NMPACKS]]も発表しました。

いくつかの曲と、その曲の関連データを一つのファイルにまとめることができます。

音楽プレイヤーに限らず、音ゲーやその他音楽と密接に関連付けたゲームやソフトの開発も楽ができるように、独自拡張がしやすいです!

/////////////////////////////////

* 仕様アップデート履歴 [#UpdateLog]
|~バージョン|~公開日|~アップデート内容|h
|0.1(初版)|2019年5月26日|1ファイルに曲関連データをまとめ上げることを目的として設計した。|
|0.1.1|2019年5月26日|誤字訂正を行った。|
|0.2|2019年5月26日|wav<楽器番号>要素を追加した。composer要素の誤字を訂正した。|
|0.2.1|2019年6月8日|album要素の誤字を訂正した。|
|0.2.2|2019年6月8日|かつて誤字のあった要素の救済措置を設定した。|
|0.3.0|2019年7月8日|データ埋め込み構文、copyright要素、date要素を追加した。|

/////////////////////////////////

* 使い方 [#HowToUse]
使い倒したい人向けに、[[仕様書:https://github.com/taka-impact/NMPACKS/blob/master/README.md]](外部サイト)が用意してありますが、最初は読まなくていいです。

** 音楽パックを作るには [#HowToMakePack]
音楽パックは次の4つの要素から構成されます。これらを必要なものだけ書き記して、拡張子.NMPのファイルとして保存します。

+ &basic{@NMTRACKS};から始まる、その音楽パックに収録されている曲IDのリスト
+ &basic{@NMPACK};から始まる、その音楽パック全体に関するデータ
+ &basic{@D_<曲ID>};から始まる、その曲IDの曲に関するデータ
+ &basic{@M_<曲ID>};から始まる、その曲IDの曲のMML

次のプログラムは一番シンプルなファイルの例です。

サンプルファイルはプチコン4専用MMLが収録されたサンプルになっているので参考にしてみてください。

なお、音楽パックファイルに動作可能なプログラムを入れると誤作動の原因になるのでご注意ください。

#basic{{
@NMTRACKS
DATA"MYBGM1"
DATA"MYBGM2"
DATA""

@NMPACK
DATA"album:はじめての きょくパック"
DATA""

@D_MYBGM1
DATA"title:はじめての きょく"
DATA"composer:○○○○"
DATA""

@M_MYBGM1
DATA"(中略:MMLデータ)"
DATA"",0

@D_MYBGM2
DATA"title:かっこいい きょく"
DATA"composer:○○○○"
DATA""

@M_MYBGM2
DATA"(中略:MMLデータ)"
DATA"",0
}}

** NMPACKS対応ソフトを作るには [#HowToMakePlayer]
基本ライブラリとして「NM One」をご用意しました。ちょっとだけ楽ができます!!

NM Oneを使うときはEXECを利用してロードするか、NM Oneの中身を全てコピーしてプログラムファイルの前や後ろに貼り付けてください。

使い方の実例は収録したサンプル「SAMPLE.PRG」をご覧ください。次に追加される主な関数を紹介します。

#region(主な関数一覧)
- &basic{NMO_INIT$(slot,mode)};
-- 戻り値は、曲ID配列。使用開始の準備をする。slotのスロットにNMPACKSフォーマットのファイルがロードされてないとSmileBASICのエラーになる。
-- slot: NMPファイルがロードされているプログラムスロット番号
-- mode: 識別文字と分割先の動作モード。&basic{NMO_GETMODECH$};関数と&basic{NMO_GETMODESU$};関数の中身を見ながら設定すること。
- &basic{NMO_GETMODECH$(mode)};
-- 戻り値は、曲IDの前につける識別文字(仕様書参照)。
-- mode: モード。モードによって返す識別文字が変化するよう適宜関数の中身を変更すること。
- &basic{NMO_GETMODESU$(mode)};
-- 戻り値は、曲データをモードによって分ける際の、分割先ラベルの@と_を含む先頭部分(仕様書参照)
-- mode: モード。モードによって返す分割先ラベルが変化するよう適宜関数の中身を変更すること。
- &basic{NMO_GET$(id$,attr$)};
-- 戻り値は、id$で指定された曲の、attr$で指定された要素の値文字列。id$に空文字列を指定した場合は&basic{@NMPACK};内からデータをロードする。要素が見つからなかった場合は空文字列を返す。
-- id$: 曲ID(単体)
- &basic{NMO_GET_PACK$(attr$)};
-- 戻り値は、&basic{@NMPACK};内の、attr$で指定された要素の値文字列。要素が見つからなかった場合は空文字列を返す。
-- attr$: 要素名。ここへの指定も大文字小文字を問わない。
- &basic{NMO_GET_FAST$(id$,attr$)};
-- 戻り値は、id$で指定された曲の、attr$で指定された要素の値文字列。挙動はNMO_GET$と同等であるが、埋め込み構文の文字列を置換しない。
-- id$: 曲ID(単体)
-- attr$: 要素名。ここへの指定も大文字小文字を問わない。
- &basic{NMO_GET_PACK_FAST$(attr$)};
-- 戻り値は、&basic{@NMPACK};内の、attr$で指定された要素の値文字列。挙動はNMO_GET_PACK$と同等であるが、埋め込み構文の文字列を置換しない。
-- attr$: 要素名。ここへの指定も大文字小文字を問わない。
- &basic{NMO_SETWAV id$,no};
-- id$で指定された曲の、noで指定された波形番号の波形を設定する。
-- id$: 曲ID(単体)
-- no: 波形番号
- &basic{NMO_SETALLWAV id$};
-- id$で指定された曲の波形を全て設定する。
-- id$: 曲ID(単体)
- &basic{NMO_BGMSET id$,no};
-- id$で指定された曲をBGM no番に設定する。曲メタデータの波形は設定されない。
-- id$: 曲ID(単体)
-- no: BGM番号
#endregion

曲再生の流れの概要をまとめると以下のようになります。

+ 適当な空きスロットに.NMPファイルをロードする
+ &basic{NMO_INIT$};関数にロードしたスロットと"識別文字と分割先の動作モード"(関数一覧参照)を渡してIDの配列を取得する
+ 再生したい曲のIDと曲を定義する定義番号を&basic{NMO_BGMSET};に渡す(必要に応じて&basic{NMO_SETALLWAV};も実行しておく)
+ &basic{BGMPLAY};で再生

最小のプログラム例を下に示しておきます。

#basic{{
EXEC"PRG2:NMONE-LIB.PRG"
EXEC"PRG1:曲ファイル"

DIM ID$[0]
ID$=NMO_INIT$(1,0)

NMO_BGMSET ID$[0],128
BGMPLAY 128
}}

また、&basic{NMO_GET$(曲ID,”TITLE”)};で曲名、&basic{NMO_GET$(曲ID,”COMPOSER”)};で作曲者などを取得可能です。

** もうちょっと作り込むには(中上級者向け) [#AdvancedMaking]
独自拡張でどんどん作り込むのもアリですが、ここでは標準で用意した一部機能を紹介します。

*** 設定可能な主な要素 [#bd12be0d]
各種要素は、適切な位置にDATA文を並べて"要素名:データ"の形式で書くことで設定できます。要素名の大文字小文字は問いません(当ページ内でも混在しています)。

次の表に示す、音楽パックファイル全体の要素は&basic{@NMPACK};のDATA文に書きます。
|~要素名|~内容|h
|album|アルバム名(音楽パックファイルの題)|

次の表に示す、曲の要素は&basic{@D_<曲ID>};のDATA文に書きます。
|~要素名|~内容|h
|title|曲のタイトル(このデータがない場合エラーとなる実装もある)|
|composer|作曲者(このデータがない場合エラーとなる実装もある)|
|wav<楽器番号>|&basic{WAVSET};用のデータ。wav224のようにして指定する。&basic{アタック,ディケイ,サスティン,リリース,定義文字列[,基準音程]};と、リファレンス通りに設定する。基準音程は省略してもよい。実装者はこのデータに対応するべき。|
|arranger|編曲者(開発者の意図としては積極的に設定&対応してほしい。)|
|lyricist|作詞者|
|description|曲の詳細およびコメント等|
|copyright|コピーライト・権利表示|
|date|制作日時(yyyy-mm-dd形式が望ましいが、区切り文字は/や漢字による助数詞も許容される)|
|lyric|歌詞(ただし、この仕様書ではフォーマットを指定しないため、非推奨)|

標準で用意してある他の要素を確認するには[[仕様書:https://github.com/taka-impact/NMPACKS/blob/master/README.md]](外部サイト)をご覧ください。

*** 特定バージョンのプチコンやSmileBASICで、別のMMLを読み込ませる [#g2cc62d5]
曲IDの前に、次のような「識別文字」を追加すると、データを読み込みラベルの「&basic{@M_};」部分が変化します。
|~対応バージョン|~識別文字|~読み込みラベル|h
|プチコン3号|#|&basic{@M3_};|
|プチコンBIG|$|&basic{@MB_};|
|PiStarter|%|&basic{@MP_};|
|プチコン4|&|&basic{@M4_};|

また、必要に応じて、自分で識別文字を追加して、読み込みラベルを変更することも可能です。NM Oneではそれが簡単にできるようになっています。

*** 埋め込み構文を使う [#y7dda55d]
&basic{[=曲ID:要素名]};という式単体もしくはembed構文を組み合わせて、他の要素に設定したデータを埋め込めるようになりました。

要素のデータがこの埋め込み式だけの場合はsame構文といい、曲ID:要素名の要素をそのままコピーします。

要素のデータ全体を&basic{{}};で囲んだ場合はembed構文といい、埋め込み式がどこにあっても埋め込み式を評価しようと試みます。

なお、どちらの構文にも当てはまらない場合は埋め込み式が評価されません。

このほか、ライブラリに関して要望等ありましたらCHECKER FLAGにお寄せください。

/////////////////////////////////

* サンプルの公開キー [#QR]
トップメニューの「作品公開とダウンロード」から公開キーを入力すると、ダウンロードすることができます。

サンプルとして、「NM One」を使用したシンプルなプレイヤーと、投稿者が[[第3回SB2Weeks:http://wiki.hosiken.jp/petc3gou/?Toukou%2FSmileBasic2weeks%20%C5%EA%B9%C6%BA%EE%C9%CA%BD%B8]]に投稿した「おてがみコウモリさん」の曲を数曲収録しました。
#ptcmid(R8PXEYD,プチコン3号/BIG版 バージョン2019-07-08)

また、[[プチコン4完全対応版>4:Toukou/プチコンシリーズ共通音楽パックフォーマット NMPACKS]]も発表しました。プチコン4ユーザの方はそちらをご利用ください。
#ptcmid(4ZSEX3ND,[参考]プチコン4版 バージョン2019-07-21)

** サンプルアップデート履歴 [#SampleUpdateInfo]
|~バージョン|~対象環境|~公開状況|~アップデート内容|h
|(初版)|3号/BIG|終了|1ファイルに曲関連データをまとめ上げることを目的として設計した。|
|(初期版)|3号/BIG|終了|バックアップがないため、詳細は不明|
|2019-07-02|4|終了|プチコン4対応版初版。ただし対応し忘れた部分がある。仕様バージョン0.2.2に対応。|
|2019-07-08|3号/BIG|公開中|仕様バージョン0.3.0に対応。NMONE-LIB.PRGは埋め込み構文にも対応した。|
|2019-07-21|4|公開中|仕様バージョン0.3.0に対応。NMONE-LIB.PRGは埋め込み構文にも対応した。|

/////////////////////////////////

* CHECKER FLAG (ひとことコメント) [#Comments]
この作品(= NMPACKSの仕様と、公開キーでアップしているサンプル)に対するコメントがあれば一言どうぞ。(作品に直接関係ない質問や雑談は[[掲示板>Board]]へ)
- ''Na'' : バグ報告 NMOME-LIB.PRG 168行目のBGMSETDでスロット1を読み込むようになっているので他のスロットでロードできません (&new{2019/06/08 (土) 20:43:14};)
- ''Na'' : "1:"+NMO_ …を STR$(_NMO_SLOT)+":"+NMO_ …とすると動きます (&new{2019/06/08 (土) 20:45:24};)
- ''投稿者'' : 修正したものをアップしました。仕様書とこのページの修正反映も間も無く行います (&new{2019/06/08 (土) 20:50:01};)
- ''投稿者'' : http://petitverse.hosiken.jp/community/petitcom/topic/?read=1321 にて、新バージョンの仕様検討を行っております。要望等があればこちらかプチバースのページへお願いします。 (&new{2019/10/22 (火) 22:43:58};)
- ''投稿者'' : http://petitverse.hosiken.jp/community/petitcom/topic/?read=1321 にて、新バージョンの仕様検討を行っております。要望等があればプチバースのページかこのコメント欄へお願いします。 (&new{2019/10/22 (火) 22:43:58};)

#comment

表示モード : [ スマホ・3DS対応表示 | クラシック表示 ]
PukiWiki 1.4.7 Copyright © 2001-2006 PukiWiki Developers Team. License is GPL. Based on "PukiWiki" 1.3 by yu-ji
ページの処理時間 : 0.017 秒 | ログイン
Copyright(C) 2011-2014 プチコンまとめWiki ◆1sxkymI8ji30