パッケージ com.lmt.lib.bms

クラス BmsLoader

  • public final class BmsLoader
extends Object
    入力データからBMSコンテンツを生成するローダーです。

    BMSライブラリは、「外部データ」からBMSコンテンツを読み込む機能を提供します。ここで言う「外部データ」とは、 BMSで記述されたテキストデータのことを指します。外部データはファイル等の何らかの形式で記録されていることを 想定しており、Java言語のInputStreamで読み取ることが出来るもの全てを指します。

    外部データの記述形式について
    外部データは上述の通り、BMSで記述されたテキストデータです。一般的には「BMSファイル」のことを指します。 BMSライブラリで読み取り可能な記述形式は一般的なBMSの仕様を取り込んでいますが、一部独自の機能を盛り込んでいます。 詳細については以下を参照してください。

    BMS宣言
    BMSの1行目において、";?bms "で始まるコメントを検出した場合、1行目をBMS宣言として解析しようとします。 BMS宣言の構文に誤りがある場合、BMS宣言は通常のコメントとして認識されるようになり、BMS宣言の無いBMSコンテンツとして 読み込まれます。BMS宣言の記述例は以下の通りです。

    ;?bms encoding="UTF-8" rule="BM"

    メタ情報
    BMSの中で「ヘッダ」と呼ばれる宣言をメタ情報として解析します。メタ情報は"#"または"%"で始まる 行が該当します。但し、BMS仕様で規定されていない名称のメタ情報はBMSコンテンツの情報としては読み込まれません。 それらの行は解析エラーとして報告されます。
    メタ情報はBMSのどこで宣言されていても問題無く読み込むことが出来ます(チャンネルを記述した後でもOK)。 但し、一般的にはメタ情報を全て宣言した後でチャンネルを記述することがほとんどのようです。
    メタ情報の記述例は以下の通りです。

    #GENRE J-POP
    #TITLE My Love Song
    #BPM 120
    %URL http://www.lm-t.com/
    %MYMETA 00AA00GG00ZZ

    チャンネル
    数字3文字＋36進数2文字＋":"で始まる行は「チャンネル」として解析します。最初の数字は小節番号、 続く36進数はチャンネル番号を表し、":"の後の記述は当該小節・チャンネルのデータを表します。 チャンネルデータの記述形式はBMS仕様によって定められているため、仕様に違反する記述をした場合、当該チャンネルは 解析エラーとして報告されます。
    一般的にチャンネルは小節番号の若い順で記述されますが、小節番号は前後しても構いません。但し、BMSの可読性が 著しく低下するので小節番号順に記述することが推奨されます。
    チャンネルの記述例は以下の通りです。

    01002:1.5
    0880A:00AB00CD00EF00GH
    123ZZ:String data channel

    エラーハンドリングについて
    通常、BMSの読み込みにおいてエラー行を検出した場合はその行を無視し、読み込みを続行することがほとんどです。 アプリケーションによっては、特定のエラーを検出した場合例外的に読み込みを中止し、読み込みエラーとして扱いたい ケースがあります。そのような場合はsetHandler(BmsLoadHandler)でハンドラを登録し、発生したエラーに応じて 読み込みの続行・中止を選択することが出来ます。発生したエラーを蓄積し、エラーをユーザーに報告するようなケースも エラーハンドリングを行うことで解決出来ます。詳細はBmsLoadHandlerを参照してください。}

    拡張したBMSコンテンツオブジェクトを読み込みたい場合
    アプリケーションによっては拡張したBMSコンテンツオブジェクト(BmsContent)を読み込みたいケースが存在します。 BmsLoaderでは読み込み時に、生成するBMSコンテンツオブジェクトを決定することが出来るようになっています。 setHandler(BmsLoadHandler)で設定したハンドラのBmsLoadHandler.createContent(BmsSpec)を オーバーライドすることによりアプリケーションで独自拡張したBMSコンテンツオブジェクトを返すことが出来ます。

    BOM付きUTF-8で記録されたBMSの読み込みについて
    外部データにBOM(Byte Order Mark)が付与された場合でも正常に読み込むことはできますが、現バージョンのBMSライブラリで 読み込めるのはリトルエンディアンの場合のみです。ビッグエンディアンで記録された外部データはサポートしていません。

    関連項目:
    [BmsLoadError] エラーハンドラに通知されるエラーの詳細情報

    • フィールドの概要

      フィールド 
      修飾子とタイプ フィールド 説明
      static BmsLoadHandler DEFAULT_HANDLER
      BMSローダのデフォルトハンドラです。

    • コンストラクタの概要

      コンストラクタ 
      コンストラクタ 説明
      BmsLoader()
      BmsLoaderオブジェクトを構築します。

    • フィールドの詳細

      • DEFAULT_HANDLER

        public static final BmsLoadHandler DEFAULT_HANDLER
        BMSローダのデフォルトハンドラです。具体的な振る舞いはBmsLoadHandlerを参照してください。

    • コンストラクタの詳細

      • BmsLoader

        public BmsLoader()
        BmsLoaderオブジェクトを構築します。

    • メソッドの詳細

      • setSpec

        public final BmsLoader setSpec​(BmsSpec spec)
        読み込み対象BMSのBMS仕様を設定します。

        ローダーは設定されたBMS仕様に従ってBMSの構文を解析します。

        パラメータ:
        spec - BMS仕様
        戻り値:
        このオブジェクトのインスタンス

      • setHandler

        public final BmsLoader setHandler​(BmsLoadHandler handler)
        BMS読み込みハンドラを設定します。

        デフォルトではDEFAULT_HANDLERが設定されています。BMS読み込み時の振る舞いを変えたい場合は 実装をカスタマイズしたBmsLoadHandlerオブジェクトを設定してください。

        nullを設定することは出来ません。nullにした状態でload(java.io.File)メソッドを呼び出すと例外がスローされます。

        パラメータ:
        handler - BMS読み込みハンドラ
        戻り値:
        このオブジェクトのインスタンス

      • setSyntaxErrorEnable

        public final BmsLoader setSyntaxErrorEnable​(boolean isEnable)
        構文エラーの有効状態を設定します。

        BMSでは、メタ情報・チャンネル定義以外の記述は全て無視される仕様になっています。BMS内での不要・不正な記述を 防ぐために、メタ情報・チャンネル定義と認識されない全ての記述を構文エラーとしたい場合に当メソッドを使用します。

        構文エラーを有効にした状態でメタ情報・チャンネル定義以外の記述を検出すると、BMS読み込みハンドラにて解析エラーを 通知するようになります。通知メソッドから解析中止が返されるとBMS解析はエラーとなります。

        デフォルトでは構文エラーは無効になっています。

        パラメータ:
        isEnable - 構文エラーの有効状態
        戻り値:
        このオブジェクトのインスタンス

      • setFixSpecViolation

        public final BmsLoader setFixSpecViolation​(boolean isFix)
        BMSライブラリの定める仕様に違反した値を自動的に仕様範囲内に丸め込むかどうかを設定します。

        この設定を有効にすることで訂正される値とは、「初期BPM」「小節長」「BPM変更用のBPM」「譜面停止時間」を指します。 それぞれの値の許容範囲はBmsSpecを参照してください。

        この設定のデフォルト値は false です。BMSライブラリ仕様の違反を検出するとローダーに設定されたBmsLoadHandler に対してエラー通知を行います。その際のエラー種別はBmsLoadError.Kind.LIBRARY_SPEC_VIOLATIONとなります。

        通常、BMSライブラリの仕様違反となる値は非常に極端な値となっており、値を訂正したとしても当該楽曲の再生には 大きな影響がない場合がほとんどですが、値の使い方次第では楽曲の構成を大きく崩してしまう可能性があります。そのような ケースが許容されない場合には仕様違反の訂正は行わず、当該楽曲の読み込みはエラーとして扱うべきです。

        この設定を有効にして読み込まれたBMSは定義上とは異なるデータとして読み込まれますので、BmsContent.generateHash() が生成する値にも影響を及ぼします。

        パラメータ:
        isFix - 仕様違反訂正の有効状態
        戻り値:
        このオブジェクトのインスタンス

      • load

        public final BmsContent load​(File bms)
                      throws BmsException
        BMSコンテンツを読み込みます。

        BMSコンテンツは指定されたファイルから読み込みます。

        読み込み処理の詳細はload(String)を参照してください。

        パラメータ:
        bms - BMSファイル
        戻り値:
        BMSコンテンツ
        例外:
        BmsException - bmsがnull: Cause NullPointerException
        BmsException - load(String)を参照

      • load

        public final BmsContent load​(Path bms)
                      throws BmsException
        BMSコンテンツを読み込みます。

        BMSコンテンツは指定されたパスが示すファイルから読み込みます。

        読み込み処理の詳細はload(String)を参照してください。

        パラメータ:
        bms - BMSファイルのパス
        戻り値:
        BMSコンテンツ
        例外:
        BmsException - bmsがnull: Cause NullPointerException
        BmsException - load(String)を参照

      • load

        public final BmsContent load​(InputStream bms)
                      throws BmsException
        BMSコンテンツを読み込みます。

        BMSコンテンツは指定された入力ストリームから読み込みます。

        読み込み処理の詳細はload(String)を参照してください。

        パラメータ:
        bms - BMSの入力ストリーム
        戻り値:
        BMSコンテンツ
        例外:
        BmsException - bmsがnull: Cause NullPointerException
        BmsException - load(String)を参照

      • load

        public final BmsContent load​(byte[] bms)
                      throws BmsException
        BMSコンテンツを読み込みます。

        BMSコンテンツは指定されたバイト配列から読み込みます。

        読み込み処理の詳細はload(String)を参照してください。

        パラメータ:
        bms - BMSのバイト配列
        戻り値:
        BMSコンテンツ
        例外:
        BmsException - bmsがnull: Cause NullPointerException
        BmsException - load(String)を参照

      • load

        public final BmsContent load​(Reader bms)
                      throws BmsException
        BMSコンテンツを読み込みます。

        File / Path / InputStream / byte[]が入力となる場合、 BmsLoaderでは最初に先頭行のBMS宣言を解析します。BMS宣言が存在し、encoding要素が存在する場合はその設定値から 使用する文字セットを解決します。以後の読み込みは当該文字セットを用いて文字列をデコードし、BMS解析を行います。

        BMS宣言が無い、またはencoding要素が指定されていない場合はBmsSpec.getStandardCharset()で取得できる 文字セットを用いてBMS解析を行います。

        BMS宣言は左から順に解析し、その順番でBMSコンテンツにセットされます。

        BMS解析の動作仕様は概ね以下の通りです。
        - 行頭の半角スペースおよびタブは無視されます。
        - 半角スペースおよびタブのみの行は空行として読み飛ばします。
        - 改行コードは<CR>, <LF>, <CR><LF>を自動認識します。
        - 先頭行において、";bms? "で始まる場合はBMS宣言として認識されます。
        - ";"または"//"で始まる行はコメント行として認識されます。(単一行コメント)
        - "/*"で始まる行は複数行コメントの開始行として認識されます。以降、行末に"* /"が出現するまでの 行は全てコメントとして認識されます。
        - 複数行コメントが閉じられずにBMS解析が終了した場合、エラーハンドラにてBmsLoadError.Kind.COMMENT_NOT_CLOSED が通知されます。
        - "#"または"%"で始まり、1文字目がアルファベットで始まる行をメタ情報の定義と見なします。
        - 3文字の半角数字で始まり、次に2文字の半角英数字、更にその次が":"で始まる行をチャンネルデータの定義と見なします。
        - 以上のパターンに該当しない行は構文エラーとし、エラーハンドラにてBmsLoadError.Kind.SYNTAXが通知されます。

        メタ情報解析について
        - メタ情報の値は、文字列の右側の半角空白文字は消去されます。
        - 索引付きメタ情報は、名称の末端文字2文字を36進数値と見なしてその値をインデックス値とし、残りの文字を名称として扱います。
        - 索引付きメタ情報のインデックス値が36進数値でない場合、エラーハンドラにてBmsLoadError.Kind.UNKNOWN_METAが通知されます。
        - BMS仕様に規定されていない名称を検出した場合、エラーハンドラにてBmsLoadError.Kind.UNKNOWN_METAが通知されます。
        - メタ情報の値がBMS仕様に規定されたデータ型の記述書式に適合しない場合、エラーハンドラにてBmsLoadError.Kind.WRONG_DATAが通知されます。

        チャンネル解析について
        - チャンネル番号がBMS仕様に未定義の場合、エラーハンドラにてBmsLoadError.Kind.UNKNOWN_CHANNELが通知されます。
        - 以下のケースを検出した場合、エラーハンドラにてBmsLoadError.Kind.WRONG_DATAが通知されます。
          - チャンネルに定義されたデータの記述書式がBMS仕様に違反している場合。
          - データ重複不許可チャンネルの同小節番号にて複数のデータ定義を検出した場合。
          - データ重複許可チャンネルの同小節番号内にてBmsSpec.CHINDEX_MAX+1個を超えるデータ定義を検出した場合。
          - 配列型チャンネルデータの配列要素数が当該小節の刻み総数より多い場合。
          - 配列型チャンネルデータの配列要素数が0。

        パラメータ:
        bms - BMSのReader
        戻り値:
        BMSコンテンツ
        例外:
        BmsException - bmsがnull: Cause NullPointerException
        BmsException - BMS仕様が設定されていない: Cause IllegalStateException
        BmsException - ハンドラが設定されていない: Cause IllegalStateException
        BmsAbortException - ハンドラ(BmsLoadHandler.parseError(com.lmt.lib.bms.BmsLoadError))がfalseを返した

      • load

        public final BmsContent load​(String bms)
                      throws BmsException
        BMSコンテンツを読み込みます。

        BmsLoaderでは、最初に先頭行のBMS宣言を解析します。BMS宣言が存在し、encoding要素が存在する場合はその設定値から 使用する文字セットを解決します。

        パラメータ:
        bms - BMSの文字列
        戻り値:
        BMSコンテンツ
        例外:
        BmsException - bmsがnull: Cause NullPointerException
        BmsException - BMS仕様が設定されていない: Cause IllegalStateException
        BmsException - BMS読み込みハンドラが設定されていない: Cause IllegalStateException
        BmsException - ハンドラが設定されていない: Cause IllegalStateException
        BmsException - BMS宣言にてencoding指定時、指定の文字セットが未知: Cause Exception
        BmsAbortException - ハンドラ(BmsLoadHandler.parseError(com.lmt.lib.bms.BmsLoadError))がfalseを返した