MikMod Sound Library

このマニュアルは、MikModSoundLibrary,version3.1.7. について記述しています。


[ Next: | Previous:Top | Up:Top ]

Introduction

The MikMod sound library は、プログラマにとって、アプリケーションに音楽や効果音を追加するいい方法です。これは強力で柔軟なライブラリで、単純でわかりやすいAPIを持っています。

それに加えて、このライブラリは移植が非常に簡単で、Unix、OS/2、MacOS、Windows など、多くのOS で利用できます。また、個人のサードパーティはその他のシステム(MS-DOS, BeOS)の移植版を作っています。

MikMod は多くのmodule のフォーマットやサウンドファイルを演奏することができます。また、sound redirection over the network のような、システム特有の特色をいかすこともできます。また、モジュール化されているため、さらに多くのサウンドやmodule のフォーマットに対応させたり、新しいハードウェアやその他の音声出力をサポートするよう拡張させることができます。


[ Next: | Previous:Introduction | Up:Top ]

Tutorial

この章は、どうやってMikModのパワーを簡単にあなたのプログラムに取り込むかについて記述しています。全てをカバーしているわけではありませんが、これは出発点ですし、あなたがこのライブラリの原理を理解することを願っています。

もしあなたがここに書くべき本当のtutorialを持っているなら、歓迎します!私のところまで送って下さい....


[ Next: | Previous:Tutorial | Up:Tutorial ]

MikMod Concepts

MikModの音声出力はいくつかの voice と呼ばれる音によって成り立っていて、それらはあなたのハードウェアの構成に応じて、ソフトウェア的に、もしくはハードウェア的にミックスされます。単純な音、例えば効果音は一つの voice しか用いませんが、sound module のような、効果音の複雑に配置されたものでは、いくつかの voice が用いられます。

MikMod の関数はグローバルにも、voiceレベルにも働きます。sound module をあつかうときと、効果音を扱う時の差は、少なくともプログラマにとってはなるべくないように設計されています。

音声の再生は sound driverが行います。MikMod は、いくつかの sound driver を提供しています。異なるハードウェアドライバ、また、ファイル、ネットワークからの情報を音声に変換するソフトウェアドライバです。また、自分自身のドライバを追加して、ライブラリに登録し、それを選ぶこともできます。(this is exactly what the module plugin of xmms does).


[ Next: | Previous:MikMod Concepts | Up:Tutorial ]

A Skeleton Program

MikMod をあなたのプログラムで使うには、いくつかのステップが必要です。

これらの条件を満たしたプログラムは以下のようになります:

/* MikMod Sound Library example program: a skeleton */

#include <mikmod.h>

main()
{
	/* register all the drivers */
	MikMod_RegisterAllDrivers();

	/* initialize the library */
	MikMod_Init("");

	/* we could play some sound here... */

	/* give up */
	MikMod_Exit();
}

このプログラムは、以下のコマンドラインでコンパイルできます: cc -o example example.c `libmikmod-config --cflags` `libmikmod-config --libs`

このプログラムは有用なことは何もしませんが、これを実行するといろいろなことが起こります。 MikMod_RegisterAllDrivers を呼ぶことによって、 MikMod ライブラリにある全てのドライバが登録されます。そして、 MikMod_Init によって、最も適当なドライバが選択されて初期化されます。これによって、このプログラムは音声をだすことができるようになります。音声が必要なくなった時は、MikMod_Exit を使ってメモリを開放して、他のプログラムがサウンドハードウェアにアクセスできるようにします。


[ Next: | Previous:A Skeleton Program | Up:Tutorial ]

Playing Modules

前述のプログラムは音をださないので、あまり有用ではありません。あなたがmodule の古典的名作 "Beyond music" のファイル(beyond music.mod)を入手したとしましょう。これをどうやって演奏したらいいのでしょうか?

これを行うためには、以下のようなコードが必要です:

/* MikMod Sound Library example program: a simple module player */

#include <unistd.h>
#include <mikmod.h>

main()
{
    MODULE *module;

    /* register all the drivers */
    MikMod_RegisterAllDrivers();

    /* register all the module loaders */
    MikMod_RegisterAllLoaders();

    /* initialize the library */
    md_mode|=DMODE_SOFT_MUSIC;
    if(MikMod_Init("")) {
        fprintf(stderr,"Could not initialize sound, reason: %s\n",
                MikMod_strerror(MikMod_errno));
        return;
    }

    /* load module */
    module = Player_Load("beyond music.mod",64,0);
    if (module) {
        /* start module */
        Player_Start(module);

        while(Player_Active()) {
            /* we're playing */
            usleep(10000);
            MikMod_Update();
        }

        Player_Stop();
        Player_Free(module);
    } else
        fprintf(stderr,"Could not load module, reason: %s\n",
                MikMod_strerror(MikMod_errno));

    /* give up */
    MikMod_Exit();
}

何が変わったのでしょうか?まず、MikMod のデバイスドライバを登録しただけでなく、module loader も登録しました。MikMod は多くの module loader を持っていて、それぞれが異なる module の型式に対応しています。 module の型式を決定するために全ての loader が呼ばれるため、その中の行く塚だけ登録して時間を節約したくなるかも知れません。この場合、あまり気にせずに全ての module loader を登録します。

次に、 MikMod_Init を呼ぶ前に、余分な行がいくつかあります。これは、 md_mode という変数を変更して、ソフトウェアで module を処理するようにライブラリに命令しています。もし GUS-type card を持っていたら、このカード用の特定のハードウェアドライバを使うことができますが、この場合、 DMODE_SOFT_MUSIC は立てないようにします。

ここで、 MikMod_Init が成功したかどうか確認しなくてはなりません。エラーがあった時は、MikMod は MikMod_errno という変数を返します。これはC ライブラリの errno と同等で、MikMod_strerrorstrerror と同等です。

さて、ここからが本題です!module は Player_Load 関数によってロードされます。この関数は module ファイルの名前と、module に割り当てる voice の数を引き数に取ります。この場合、この module は4チャンネルしかないので、4つの voice を割り当てますが、 Impulse Tracker の複雑なモジュールではたくさんのvoice が必要になる場合があります(as they can have as many as 256 virtual channels with so-called "new note actions")。空の voice を処理する時間はかからないため、この部分は大きい数、例えば64とか128などを当てておけば安全です。もう一つの引き数は loader の "curiosity" を決定します。もし0 でない場合、loader は module の隠された部分を検索します。しかし、module 型式でこのような部分を持っているものは少ないので、ここでは0を使います。

これで module を演奏する準備が整ったので、演奏してみましょう。 Player_Start 関数を使って、playerに現在の module は module であると伝えます。これによって再生がはじまりますが、これを定期的にアップデートしなくてはなりません。そのため、 Player_Active 関数を使ったループがありますが、この関数は module の演奏が終わったかどうかを知る関数です。音声をアップデートするには、単純に MikMod_Update 関数を呼びます。

module の演奏が終わったあと、Player_Stop 関数を使ってplayer に演奏が終わったことを伝え、 Player_Free 関数を使って module を開放します。


[ Next: | Previous:Playing Modules | Up:Tutorial ]

Playing Sound Effects

MikMod は、module を演奏するだけに留まらず、効果音、つまり、module のサンプルを鳴らすこともできます。これはmodule を演奏するよりも少し複雑になるのですが、これは module player が多くのことをしてくれるのに対して、この場合はプログラムによって実際には何が演奏されるのかもっと制御しなくてはならないからです。例を見てみましょう:

/* MikMod Sound Library example program: sound effects */

#include <unistd.h>
#include <mikmod.h>

main()
{
    int i;
    /* sound effects */
    SAMPLE *sfx1,*sfx2;
    /* voices */
    int v1,v2;

    /* register all the drivers */
    MikMod_RegisterAllDrivers();

    /* initialize the library */
    md_mode|=DMODE_SOFT_SNDFX;
    if(MikMod_Init("")) {
        fprintf(stderr,"Could not initialize sound, reason: %s\n",
                MikMod_strerror(MikMod_errno));
        return;
    }

    /* load samples */
    sfx1 = Sample_Load("first.wav");
    if(!sffx1) {
        MikMod_Exit();
        fprintf(stderr,"Could not load the first sound, reason: %s\n",
                MikMod_strerror(MikMod_errno));
        return;
    }
    sfx2 = Sample_Load("second.wav");
    if(!sfx2) {
        Sample_Free(sfx1);
        MikMod_Exit();
        fprintf(stderr,"Could not load the second sound, reason: %s\n",
                MikMod_strerror(MikMod_errno));
        return;
    }
    /* reserve 2 voices for sound effects */
    MikMod_SetNumVoices(-1,2);

    /* get ready to play */
    MikMod_EnableOutput();

    /* play first sample */
    v1=Sample_Play(sfx1,0,0);
    for(i=0;i<5;i++) {
        MikMod_Update();
        usleep(100000);
    }

    /* half a second later, play second sample */
    v2=Sample_Play(sfx2,0,0);
    do {
        MikMod_Update();
        usleep(100000);
    } while(!Voice_Stopped(v2));

    MikMod_DisableOutput();

    Sample_Free(sfx2);
    Sample_Free(sfx1);

    MikMod_Exit();
}

前の例と同じように、まず sound driver を登録して、ライブラリを初期化します。また、md_mode 変数を変えて、ソフトウェアでミックスするように設定します。

次に、 Sample_Load 関数を使ってファイルをロードします。戻り値をチェックするのを忘れないで下さい。このような小さいプログラムでは見苦しく見えるかも知れませんが、いい練習になります...

二つのサンプルを演奏したいので、少なくとも二つの voice が必要です。したがって、 MikMod_SetNumVoices を使って予約します。最初の引き数は module の voice の数、二番目の引き数は効果音の voice の数です。ここでは module の voice の数は設定しないので、現在の値を保持するために -1 を入れます。

これで演奏する準備が整ったので、 MikMod_EnableOutput を呼んでドライバの準備をします。効果音は Sample_Play 関数を使って鳴らすことができます。そのために、どの sample を鳴らすか、どの場所から始めるかのオフセット、それと再生フラグを指定する必要があります。これについてはあとで詳細に説明します。この関数は、そのサンプルと関連したvoice の数を返します。

最初のサンプルは1/2秒鳴らして、次のサンプルを鳴らします。二つのチャンネルを予約しているため、両方のサンプルが同時に鳴ります。再生を止めるには Voice_Stopped 関数を使います:これは現在のvoice の状態をあらわす引き数を返します。これは、サンプルが演奏されている時は0、演奏が終わったあとは0以外の値になります。従って、 do ループは、一番目のサンプルの長さに関わらず、二番目のサンプルが終わった直後に終了します。

終了するには、Sample_Free を使ってサンプルを開放します。


[ Previous:Playing Sound Effects | Up:Tutorial ]

More Sound Effects

効果音は、再生に影響するいくつかの属性を持っています。たとえば、スピード、panning、ボリュームなどです。 voice number を使って、これらの属性を Voice_SetFrequency, Voice_SetPanning ,Voice_SetVolume 関数を使って調節することができます。

前の例の、実際に音をだしている部分のコード(MikMod_EnableOutputMikMod_DisableOutputの間の部分)を、以下のコードに置き換えます:

    Sample_Play(sfx1,0,0);
    for(i=0;i<5;i++) {
        MikMod_Update();
        usleep(100000);
    }
    v2=Sample_Play(sfx2,0,SFX_CRITICAL);
    i=0;
    do {
        MikMod_Update();
        usleep(100000);
        v1=Sample_Play(sfx1,0,0);
        Voice_SetVolume(v1,160);
        Voice_SetFrequency(v1,(sfx1->speed*(100+i))/100);
        Voice_SetPanning(v2,(i++&1)?PAN_LEFT:PAN_RIGHT);
    } while(!Voice_Stopped(v2));

初めに気がつくのは、二番目のサンプルを演奏する時に SFX_CRITICAL フラグが使われていることです。 do ループが他のサンプルを100ミリ秒毎に付け加えて、しかも二つしかvoice を予約していないため、古いvoice から必要になるごとに削除されていきます。これによって、二番目のサンプルは二回目のループで削除されてしまうように見えます。しかし、この音が "critical" であるというフラグを立てているために、音自体が終了するかVoice_Stop 関数を呼ぶまで二番目のサンプルは削除されません。したがって、一番目のサンプルがループの度に止まるのに対し、二番目の音は最後まで演奏されます。

次に、一番目のサンプルを少し小さい音で演奏するために、Voice_SetVolume 関数が使われています。ボリュームは0(沈黙)から256の間です。この場合、サンプルは160で演奏しています。この音を不思議な感じにするため、 Voice_SetFrequency を使って周波数を変えています。サンプルコードの計算によって、周波数はだんだん高くなって行きます(最初はサンプル固有の周波数からはじまって、ループ一回ごとに1%づつ周波数が増えて行きます)。

Voice_SetPanning 関数の効果を試すため、二番目のサンプルの panning をループ一回ごとに左から右に変化させています。引き数は標準的な panning である PAN_LEFT, PAN_RIGHT, PAN_CENTER and PAN_SURROUND1、または0 (PAN_LEFT) と255 (PAN_RIGHT) の間の数値を取ります。


[ Next: | Previous:Tutorial | Up:Top ]

Using the Library

この章は、ライブラリのいろいろな部分とその使用法について記述しています。


[ Next: | Previous:Using the Library | Up:Using the Library ]

Library Version

もしもあなたのプログラムが MikMod ライブラリと動的にリンクされているのであれば、どのバージョンのライブラリを使っているのかチェックした方がいいでしょう。これを行うために、ライブラリはいくつかの定数と関数を提供していて、今のライブラリが適当なのか、アップグレードしなければいけないのか決定できるようになっています。

プログラムに mikmod.h をインクルードすると、以下の定数が定義されます:

従って、プログラムがどのバージョンのライブラリをコンパイルしたか、いかのようにしてしることができます:

printf("Compiled with MikMod Sound Library version %ld.%ld.%ld\n",
       LIBMIKMOD_VERSION_MAJOR,
       LIBMIKMOD_VERSION_MINOR,
       LIBMIKMOD_REVISION);

ライブラリは MikMod_GetVersion 関数を定義していて、これはライブラリの LIBMIKMOD_VERSION の値を返します。もしこの値があなたの LIBMIKMOD_VERSION 以上だったら、あなたのプログラムは正常に動きます。そうでなければ、ライブラリをアップデートするようにユーザーに知らせなければなりません:

{
    long engineversion=MikMod_GetVersion();

    if (engineversion<LIBMIKMOD_VERSION) {
        printf("MikMod library version (%ld.%ld.%ld) is too old.\n",
               (engineversion>>16)&255,
               (engineversion>>8)&255,
               (engineversion)&255);
        printf("This programs requires at least version %ld.%ld.%ld\n",
               LIBMIKMOD_VERSION_MAJOR,
               LIBMIKMOD_VERSION_MINOR,
               LIBMIKMOD_REVISION);
        puts("Please upgrade your MikMod library.");
        exit(1);
    }
}


[ Next: | Previous:Library Version | Up:Using the Library ]

Type Definitions

MikMod は、 module やサンプルを扱うために、いくつかのデータ型を定義しています。これらの型は、MikMod が移植された全てのプラットフォームで同じメモリサイズを持っています。

それらの型は以下の通りです:


[ Next: | Previous:Type Definitions | Up:Using the Library ]

Error Handling

MikMod は正常に働くために最善を尽くすのですが、不幸にもそうならない時があります。たとえば、もしあなたが破損したファイルを演奏しようとした場合、演奏できません。多くの MikMod 関数は、ポインタかBOOL 値を返します。もしもポインタが NULL か、 BOOL が 0 (false) だった場合、エラーが起こっています。

MikMod のエラーは、 MikMod_errno という変数で帰ってきます。それぞれの可能性のあるエラーは MMERR_ で始まるエラーコードを持っています。例えば、もし MikMod がファイルを開くことができなかった場合、MikMod_errnoMMERR_OPENING_FILE という値を受け取ります。

MikMod_strerror を使うと、表示するための適切なエラーメッセージを受け取ることができます。

その他に、MikMod_critical という名前のエラー変数があります。その名前の通り、ライブラリが不安定になるようなエラーが生じた時のみこの変数はセットされます。この変数がセットされるのは MikMod_InitMikMod_SetNumVoicesMikMod_EnableOutput 関数の時だけです。これらの関数のどれかがエラーを返して MikMod_critical がセットされた場合、ライブラリは初期化されていない状態(つまり、初期化されていないか、 MikMod_Exit が呼ばれた状態)になっています。

エラーが起きたことを知るために、コールバック関数を使うこともできます。この関数は void MyFunction(void) というかたちでプロトタイプを書かなくてはなりません。次に、MikMod_RegisterHandler という関数を、あなたの書いたエラーを知らせるための関数を引き数として呼びます。一度に一つのコールバック関数しか登録できませんが、MikMod_RegisterHandler は以前のハンドラを返すので、ハンドラを連鎖させることはできます。


[ Next: | Previous:Error Handling | Up:Using the Library ]

Library Initialization and Core Functions

ライブラリを初期化するためには、まずサウンドドライバを登録しなくてはなりません。MikMod_RegisterAllDrivers を使ってライブラリにある全てのドライバを登録することもできますし、MikMod_RegisterDriver を使ってその中の一部だけを登録することもできます。もしもドライバを手動で登録する場合、順番に気をつけなくてはなりませんが、それは MikMod_Init がドライバをあなたが登録した順番に試していくからです。 MikMod_RegisterAllDrivers 関数はまずネットワークドライバ(ネットワーク上の音を再生する)を最初に登録して、次にハードウェアドライバ、次に disk writers、最後に nosound driver を登録します。 nosound driver を最初に登録してしまうのはあまりいい考えではありません...

MikMod_InfoDriver 関数によって、登録したドライバに関する表示可能な情報を得ることができます。帰り値の文字列が必要無くなったら free を呼ぶのを忘れないで下さい。

ドライバを登録したあとは、MikMod_Init 関数を使って、必要ならドライバに特定の情報を渡して、音の再生を初期化することができます。 md_device を0(デフォルト)に設定すると、ドライバは自動的に選択されます。つまり、そのシステムで利用できるドライバのリストのなかの最初のものが使用されます。その他の場合、登録されたドライバのリストの md_device 番目のものだけが試されます。もしあなたの再生の設定(md_mixfreqmd_mode)がサポートされていない場合は、MikMod_Init は失敗します。

MikMod_SetNumVoices 関数で必要な voice の数を選んで、MikMod_EnableOutput関数で再生をはじめることができます。

音のミックスのため、 MikMod_Update をなるべく頻繁に呼ぶことを忘れないで下さい。もしも必要なら、これを行うだけのプロセスを分岐させるか、またはライブラリがあなたのシステムでスレッドに対応しているなら、このためだけのスレッドを作って下さい。

再生の設定を変える場合、ほとんどの場合は再生途中に変更することはできません。一度再生を止めて、ドライバを初期化しなおさなければなりません。MikMod_Active を使って、音がまだ再生されているかどうかチェックして下さい。再生中の場合、MikMod_DisableOutput を使って再生を止めて下さい。次に、設定を変更してから、 MikMod_Reset 関数を呼んで下さい。あとは前述のように voice の数を選んで再生を再開できます。

プログラムを終了する時は、サウンド関係のハードウェアを首尾一貫した状態にとどめるため、再生を終了して、 MikMod_Exit を呼ぶのを忘れないで下さい。

スレッドを持ったシステムの場合、 libmikmod はthread-safe2です。これをチェックするには、MikMod_InitThreads 関数を使います。もしこの関数が1を返したら、ライブラリは thread-safe です。

thread-safe であることによる主な利点は、 MikMod_Update が別のスレッドから呼ぶことができて、アプリケーションの設計が簡単になることです。しかし、いくつかの libmikmod のグローバル変数が全てのスレッドから参照できるため、これらのアクセスを制限するために MikMod_LockMikMod_Unlock 関数を使って下さい。もし libmikmod が thread-safe でない場合、これらの関数は何も行いません。


[ Next: | Previous:Library Initialization | Up:Using the Library ]

Samples and Voice Control

今のところ、MikMod は非圧縮のモノラルWAV ファイルしかサンプルとしてサポートしていません。サンプルをロードするには、 ファイル名を使ってSample_Load関数 を呼ぶか、 FILE* ポインタを使ってSample_LoadFP 関数を呼んで下さい。これらの関数は、 SAMPLE 構造体のポインタを返すか、エラーの場合は NULL を返します。

SAMPLE 構造体はいくつかの興味深いフィールドがあります:The SAMPLE structure has a few interesting fields:

これらのフィールドの一つを変えると、サンプルの中の全てのボリュームが変更されます。一つのvoiceに対しても Voice_SetFrequency, Voice_SetVolume and Voice_SetPanning を使って同じようなことができます。 サンプルが異なる周波数、ボリューム、panning で演奏できるので、voice固有の情報をVoice_GetFrequency, Voice_GetVolume and Voice_GetPanning で獲得することができます。

また、 loopstartloopend を設定して、 flagsSF_LOOP でorをかけることによって、サンプルをループさせることもできます。ループに使う値を計算するのに、 length フィールドが有用でしょう。しかし、全てのサンプルの長さは expressed in samples、つまり、8ビットのサンプルなら8ビット、16ビットのサンプルだったら16ビットになります。 flagsSF_16BITS で確認して下さい。

フラグについていえば、libmikmod はサンプルデータに内部で処理をするので、ディスク上のサンプルのもともとのフォーマットを知りたい時は、 inflags フィールドを参照して下さい。

もし一般的な forward loop が不十分なら、他のフラグを調節することもできます: SF_BIDI によって、サンプルのループを "ping pong" (前後に行き来する)にすることができ、SF_REVERSE によって逆向きに演奏することができます。

サンプルを演奏するには、 Sample_Play 関数を使います。この関数はvoice の番号を返すので、これによって Voice_xx 関数を使うことができるようになります。

サンプルは、SFX_CRITICALがセットされていない場合、他のサンプルがとって変わって演奏される(登録した効果音のvoice の数より多くのサンプルを演奏した場合)までしか演奏されません。強制的に演奏を止めるには Voice_Stop、他のサンプルをそのサンプルにとって変わって演奏させるには Voice_Play 関数を使います。しかし、 Voice_Play では、新しいサンプルのフラグをcritical にすることはできません。

ループのないサンプルでは、演奏が終わるとすぐにvoice チャンネルが開放されます。現在のサンプルの再生位置を知るにはVoice_GetPositionを使います。もしもこれが0なら、サンプルの演奏が終わったか、演奏がちょうど始まったところかのいずれかです。Voice_Stopped によって区別することができます。

サンプルがもう必要なくなった時は、Sample_Free を使ってメモリを開放するのを忘れないで下さい。


[ Next: | Previous:Samples and Voice Control | Up:Using the Library ]

Modules and Player Control

サウンドドライバに関して、MikMod で moduleをロードするためにmodule loader を登録しなくてはなりません。 MikMod_RegisterAllLoaders 関数を使って全ての module loader を登録するか、MikMod_RegisterLoader 関数を使って一部だけを登録することができます。このような場合注意すべきことは、 15 instrument MOD loader は最後に登録すべきということです。なぜなら loader はあなたが登録した順にモジュールを認識しようとするのですが、このフォーマットの検出は完全に信頼できるものではないため、他の型式が 15 instrument MOD file と誤って認識される可能性があります。

MikMod_InfoLoader を使うと、登録した loader に関する表示可能な情報を得ることができます。必要なくなった時は返り値の文字列に free をかけることを忘れないで下さい。

サウンドドライバと異なり、 module loader はいつでも登録することができます。

プレイリストを作るために、module のタイトルを知りたくなるかも知れません。そのような場合、Player_LoadTitle によってその情報を得ることができます。必要なくなった時は返り値の文字列に free をかけることを忘れないで下さい。

module をロードするには、 Player_Load 関数を使って module の名前でロードするか、 Player_LoadFP を使って FILE* ポインタを使ってロードするかのいずれかを使います。これらの関数はまた voice の数と curiosity flag を引き数として持ちます。得に理由がなければ、 voice の数には64、またはImpulse Trackerの複雑な module の場合は128 など、大きな数を選んで下さい。どちらの関数も、MODULE 構造体へのポインタを返します。エラーが起きた場合は、 NULL を返します。

この構造体の中に、いくつか有用な情報があります:

module がロードされたら、 Player_Start を使って、 module player にある特定の module を演奏するように伝えることができます。(プレイヤーは一度に一つの module しか演奏できませんが、いくつかの module を同時にメモリにロードすることはできます。)これによって再生が始まります。もしもどの module が演奏しているか知りたければ、 Player_GetModule によって知ることができます。

現在演奏中の曲の位置をはPlayer_NextPosition, Player_PrevPosition 関数で変化させることができます。曲のスピードは Player_SetSpeedPlayer_SetTempo関数で変化させることができます。ボリュームはPlayer_SetVolumeで変更できます。

再生は Player_TogglePause 関数を使って一時停止したり、再開させたりできます。 Player_Paused 関数を使って、今プレイヤーがどのような状態にあるのかチェックして下さい。

Player_MutePlayer_UnMutePlayer_ToggleMute を使うと、チャンネルの一部の音を消したりもとに戻したりすることによって、より細かいプレイヤーの調節ができます。 Player_Muted は、現在のチャンネルの状態を返します。さらに細かい調節をしたい時は、 Player_GetChannelVoice 関数を使って、対応するチャンネルの voice を取り出して、直接 voice に働きかけることができます。

module は一度しか演奏されませんが、 module がループするようになっていれば無限にくり返されます。これを変えるには MODULE 構造体の wraploop を使います。最初の変数がセットされると、 module が終わるとまた最初から演奏され、二番目の変数がセットされると、 module の再生位置が後ろの方にジャンプするのを防ぎます。

module が 演奏されているかどうかは Player_Active によって知ることができ、また再生は Player_Stop を使っていつでも止めることができます。module が必要なくなった時は、 Player_Free を使ってメモリを開放します。


[ Previous:Modules and Player Control | Up:Using the Library ]

Loading Data from Memory

もしも module や効果音をファイル以外のところからロードする場合、 MREADERMWRITER オブジェクトを使います。

MREADERMWRITER 構造体は、関数のポインタのリストを持っており、通常の FILE * オブジェクトの振る舞いをエミュレートします。実際は、ファイル名や FILE * を引き数に持つ全ての関数は、 MREADERMWRITER を引き数に持つ実際の関数のwrapper に過ぎません。

従って、module をメモリや、いくつかのファイルからなるアーカイブからロードしたい場合、適切な MREADER オブジェクトを作って、 Player_LoadPlayer_LoadFP のの代わりにPlayer_LoadGeneric を使います。サンプルの場合は、Sample_LoadSample_LoadFP の代わりに Sample_LoadGeneric を使います。


[ Next: | Previous:Using the Library | Up:Top ]

Library Reference

この章は、ライブラリが提供する全ての関数、変数の詳細を記述しています。基本的な型に関してはType Definitionsを参照して下さい。


[ Next: | Previous:Library Reference | Up:Library Reference ]

Variable Reference

Error Variables

以下の変数は、ライブラリのエラーに関する情報を返します。

int MikMod_errno
エラーが起こった場合、この変数はエラーコードを返します。詳細は Error Referenceを参照して下さい。
BOOL MikMod_critical
この変数は、エラーが起きた場合にその深刻さを返します。この値は MikMod_errno が0以外の値の時だけ意味を持ちます。 MikMod_critical の値が 0 でない場合、エラーは致命的ではなく、ライブラリは安定した状態にあります。それに対して、これが0でない場合は、ライブラリは使用することができず、初期化されていない状態にリセットされます。これは通常、あなたの選んだmixingのパラメータがドライバにサポートされていないか、MikMod_SetNumVoices を呼んだ場合の必要なvoice の数が確保できなかった場合です。

Sound Settings

以下の変数は音声出力のパラメータを調節します。これらを変化させた場合、その効果はすぐにあらわれます。

UBYTE md_musicvolume
モジュールのボリュームをあらわします。0 から 128 の値を取ります。デフォルトは128です。
UBYTE md_pansep
ステレオチャンネルの分離を表します。0 (分離なし。モノラルサウンド)から128(完全にチャンネル分離)の値を取ります。デフォルトは128です。
UBYTE md_reverb
音のリバーブを表します。0(リバーブなし)から15(ほとんどカオスです...)の値を取ります。デフォルトは6です。
UBYTE md_sndfxvolume
効果音のボリュームを表します。0 から 128 の値を取ります。デフォルトは128です。
UBYTE md_volume
音の全体のボリュームを表します。0から128の値を取ります。デフォルトは96です。

Driver Settings

以下の変数はより内部的な音声出力のパラメータです。いくつかの md_mode フラグを除いて、これらを変化させても MikMod_InitMikMod_Resetを呼ぶまでは効果が出ません。

UWORD md_device
この変数は、登録されたドライバのリストの中で、音の再生に使われるドライバの順番を表します。This order is one-based;もしもこの変数を0に設定した場合、ドライバは自動的に選択されます。つまり、ドライバがシステム内にあるかどうか、リストが順番にテストされます。デフォルトは0で、つまりドライバは自動的に選択されます。
MDRIVER* md_driver
この変数は、音声の再生に使われているドライバに対するポインタを返します。ライブラリが初期化されていない場合( MikMod_Init が呼ばれる前、または MikMod_Exit が呼ばれたあと)は定義されません。この値は参照するだけで、これを変化させようとしてはいけません。 md_driverMikMod_Init、(または MikMod_Reset)をかわりに使って下さい。
UWORD md_mixfreq
音声の再生の周波数をヘルツで表します。この値が大きいと高品質の再生を行いますが、小さい値の場合より計算機のパワーを使います。デフォルトは 44100 Hz で、これは CD と同じ品質です。その他の良く使われる値は 22100 Hz (ラジオと同等)、11025 Hz (電話と同等)、8000 Hz (mu-law quality) です。
UWORD md_mode
この変数はいくつかのフラグの組み合わせで、出力のモードを選択できます。以下のフラグは音声出力に直接働きます(つまり、効果がすぐにあらわれます)。
DMODE_INTERP
このフラグを立てると、ミキサーが補間を行います。これによって音質は上がりますが、標準的なミックスよりも時間がかかります。ミキサーが高品質の場合、この補間はこのフラグと関係なく常に行われます。
DMODE_REVERSE
このフラグを立てると、右と左のステレオチャンネルが入れ代わります。
DMODE_SURROUND
このフラグを立てると、サラウンドでミックスされます。これはステレオの音でなくては効果がないため、再生がモノラルの場合はこのフラグは効果がありません。

以下のフラグは、サウンドドライバが変更されるかリセットされるまで効果があらわれません:
DMODE_16BIT
このフラグを立てると、16ビットサウンドモードになります。これによって音質は上がりますが、よりミックスに時間がかかるようになります。
DMODE_HQMIXER
このフラグを立てると、高音質のソフトウェアミキサーが選択されます。このモードによって音質は向上しますが、よりミックスに時間がかかります。もちろん、 DMODE_SOFT_xx フラグが立っていないとこのフラグは効果がありません。
DMODE_SOFT_MUSIC
このフラグを立てると、module をソフトウェアでミックスします。
DMODE_SOFT_SNDFX
このフラグを立てると、効果音をソフトウェアでミックスします。
DMODE_STEREO
このフラグを立てると、再生がステレオになります。

The default value of this variable is DMODE_STEREO | DMODE_SURROUND | DMODE_16BITS | DMODE_SOFT_MUSIC | DMODE_SOFT_SNDFX.


[ Next: | Previous:Variable Reference | Up:Library Reference ]

Structure Reference

利用価値のあるフィールドだけが記載されています。もし構造体のフィールドが記載されていない場合、そのフィールドは内部で使用するためのもので、改変してはいけません。

Drivers

MDRIVER構造体はライブラリの内部で使われる以外のことは想定されていませんが、最初の4つのフィールドは、あなたのプログラムにとって有用であろう情報を含んでいます:

CHAR* Name
ドライバの名称です。通常20文字以内です。
CHAR* Description
ドライバに関する記述です。通常50文字以内です。
UBYTE HardVoiceLimit
このドライバのハードウェアのvoice の数の最大値です。ハードウェアのミキシングをサポートしていない場合は0です。
UBYTE SoftVoiceLimit
このドライバのソフトウェアのvoice の数の最大値です。ソフトウェアのミキシングをサポートしていない場合は0です。
UBYTE Alias
ドライバの短縮名です。スペースを含まず、通常10文字以内です。

Modules

MODULE 構造体は、ファイル型式に関わらず、module ファイルを再生するために必要な全ての情報を持っています。

General Module Information

この章で記述されているフィールドは module の一般的な情報で、改変してはいけません。

CHAR* songname
module の名前。
CHAR* modtype
module の型式(どのトラッカーの型式か)
CHAR* comment
module のコメントか、もしコメントのない場合は NULL になります。
UWORD flags
いくつかの module のフラグがorで一緒になっています。
UF_ARPMEM
このフラグを立てると、I arpeggio effects have memory.
UF_BGSLIDES
このフラグを立てると、volume slide effects が、次の音符か次の効果が再生されるまで続きます。
UF_HIGHBPM
このフラグを立てると、255以上のテンポ(bpm)を設定することができます。
UF_INST
このフラグが立っている場合、そのモジュールはinstrumentとsampleの両方を持っています。そうでない場合、モジュールはsampleしかもっていません。
UF_LINEAR
このフラグを立てると、slide の周期が線形になります。そうでない場合、対数的になります。
UF_NNA
このフラグを立てると、モジュールは new note actions (NNA) を使うようになり、 numvoices フィールドが有効になります。
UF_NOWRAP
このフラグを立てると、最後のパターンの終了から最初のパターンに続いて演奏されなくなります。
UF_S3MSLIDES
このフラグを立てると、モジュールは古いS3Mスタイルのボリュームスライド(スライドがtick毎に実行されます)。その他の場合、標準的なスタイル(スライドは、最初のtick以降に実行されます)が使用されます。
UF_XMPERIODS
このフラグを立てると、モジュールはXM 型のperiod を使います。その他の場合、Amiga タイプの period を使います。

UBYTE numchn
モジュールのチャンネルの数を表します。
UBYTE numvoices
モジュールがNNAを使っていて、この変数が0でない場合、モジュールのvoice の最大数を返します。そうでない場合、その最大数は Player_Loadxx 関数の maxchan 変数にセットされます。
UWORD numpos
モジュールのposition の数を返します。
UWORD numpat
パターンの数を返します。
UWORD numins
instrument の数を返します。
UWORD numsmp
sample の数を返します。
INSTRUMENT* instruments
instrument 構造体の配列へのポインタです。
SAMPLE* samples
sample 構造体の配列へのポインタです。
UBYTE realchn
この変数は、再生の途中でアクティブなチャンネルの数を返します。(NNA channel は含みません)

Playback Settings

ここで記述されているフィールドはモジュールの再生をコントロールします。これらは、特に指定されていない限り、いつでも変更することができます。

UBYTE initspeed
モジュールの最初のスピードを表します(Protracker 互換)。1-32の値を取ります。
UBYTE inittempo
モジュールの最初のテンポを表します。(Protracker 互換)32-255の値を取ります。
UBYTE initvolume
モジュールの最初のボリュームを表します。0-128の値を取ります。
UWORD panning[]
現在のチャネルのpanning position を表します。 Only the first numchn values are defined.
UBYTE chanvol[]
現在のチャネルのボリュームを表します。 Only the first numchn values are defined.
UWORD bpm
現在のモジュールのテンポを表します。これを変化させるためには Player_SetTempo を使います。
UBYTE sngspd
現在のモジュールのスピードを表します。これを変化させるためには Player_SetSpeed を使います。
UBYTE volume
モジュール全体のボリュームを表します。0-128の値を取ります。値を変化させるためにはPlayer_SetVolume を使います。
BOOL extspd
これが 0 の場合、Protracker の extended speed effect (モジュール内でのテンポの修正)は処理されません。デフォルトは1で、このエフェクトは処理されます。しかし、古いモジュールでは、このエフェクトをオフにしないと正しく演奏されない可能性があります。
BOOL panflag
これが 0 の場合、panning effect は処理されません。デフォルトは1で、すべての panning effect は処理されます。しかし、古いモジュールでは、このエフェクトをオフにしないと正しく演奏されない可能性があります。
BOOL wrap
これが0でない場合、モジュールは演奏が終わったあと最初の位置に戻って連続的に演奏します。デフォルトは0です。(一度しか演奏されません)
UBYTE reppos
モジュールがwrapする際に再生を始める位置を表します。
BOOL loop
0でない場合、すべてのモジュールのループが処理されます。そうでない場合、現在の再生位置より前に移動する、後ろ向きのループは処理されません。(つまり、前向きのループおよび同じパターン内にある後ろ向きループしか処理されません)これによって、モジュールがエンドレスにループすることが避けられます。デフォルトは1出す。(すべてのループが処理されます)
BOOL fadeout
0でない場合、モジュールの最後の位置が演奏されている間にボリュームがフェードアウトします。デフォルトは0です(フェードアウト無し)。
UWORD patpos
パターン内の現在演奏されている位置 (row) です。変更することはできません。
SWORD sngpos
現在の曲の中の位置です。直接この変数を変えずに、Player_NextPosition, Player_PrevPosition ,Player_SetPosition を使って下さい。
ULONG sngtime
曲の経過時間です。2^-10 秒単位(正確にミリ秒ではありません)で表されます。この値を秒数に変換するには、1024で割って下さい。
UBYTE realchn
現在アクティブなモジュールのチャンネル数を表します。( NNA virtual channels は含みません。)
SWORD relspd
相対的な再生スピードを表します。この変数の値をモジュールのテンポに加えたものが実際の再生スピードとなります。デフォルトは0で、モジュールは作者の意図通りのスピードで再生されます。

Module Instruments

INSTRUMENT 構造体はライブラリ内部で使用するための物ですが、名前を知りたい場合があるかもしれません:

CHAR* insname
instrument のテキストです。理論的には名前、ということになっていますが、普通はメッセージラインとして使われます。

Samples

SAMPLE 構造体は効果音、モジュールのサンプルとして使われます。いかのフィールドを変更することができます:

SWORD panning
サンプルの Panning value を表します。有効範囲は PAN_LEFT (0) からPAN_RIGHT (255) まで、もしくは PAN_SURROUND です。
ULONG speed
サンプルの再生周波数(Hz)です。
UBYTE volume
サンプルの音量です。0-64の値を取ります。
UWORD flags
メモリ内のサンプルのフォーマットを表すフラグです。

Format flags:

SF_16BITS
このフラグが立っていると、サンプルデータは16ビットです。そうでない場合、8ビットです。
SF_BIG_ENDIAN
このフラグが立っていると、サンプルデータはbig-endian (Motorola) 型です。それ以外の場合、little-endian (Intel) 型です。
SF_DELTA
このフラグが立っていると、サンプルは delta values (differences between two consecutive samples) として記憶されます。その他の場合、サンプルは sample values として保存されます。
SF_ITPACKED
このフラグが立っていると、サンプルデータは Impulse Tracker 型式の圧縮法で圧縮されます。その他の場合、サンプルは圧縮されません。
SF_SIGNED
このフラグが立っていると、サンプルデータは符号付きの値でできています。そうでない場合、符号無しの値でできています。
SF_STEREO
このフラグが立っていると、サンプルデータはステレオ(2チャンネル)です。そうでない場合、モノラルです。

Playback flags:
SF_BIDI
If set, sample loops "ping pong" (back and forth).
SF_LOOP
If set, sample loops forward.
SF_REVERSE
If set, sample plays backwards.

UWORD inflags
Same as "flags", but describing the format of the sample on disk.
ULONG length
Length of the sample, in samples. The length of a sample is 8 bits (1 byte) for a 8 bit sample, and 16 bits (2 bytes) for a 16 bit sample.
ULONG loopstart
Loop starting position, relative to the start of the sample, in samples.
ULONG loopend
Loop ennding position, relative to the start of the sample, in samples.

MREADER

The MREADER contains the following function pointers:

BOOL (*Seek)(struct MREADER*,long offset,int whence)
This function should have the same behaviour as fseek, with offset 0 meaning the start of the object (module, sample) being loaded.
long (*Tell)(struct MREADER*)
This function should have the same behaviour as ftell, with offset 0 meaning the start of the object being loaded.
BOOL (*Read)(struct MREADER*,void *dest,size_t length)
This function should copy length bytes of data into dest, and return zero if an error occured, and any nonzero value otherwise. Note that an end-of-file condition will not be considered as an error in this case.
int (*Get)(struct MREADER*)
This function should have the same behaviour as fgetc.
BOOL (*Eof)(struct MREADER*)
This function should have the same behaviour as feof.

For an example of how to build an MREADER object, please refer to the MFILEREADER object in file mmio/mmio.c in the library sources.

MWRITER

The MREADER contains the following function pointers:

BOOL (*Seek)(struct MWRITER*,long offset,int whence);
This function should have the same behaviour as fseek, with offset 0 meaning the start of the object being written.
long (*Tell)(struct MWRITER*);
This function should have the same behaviour as ftell, with offset 0 meaning the start of the object being written.
BOOL (*Write)(struct MWRITER*,void *dest,size_t length);
This function should copy length bytes of data from dest, and return zero if an error occured, and any nonzero value otherwise.
BOOL (*Put)(struct MWRITER*,int data);
This function should have the same behaviour as fputc.

For an example of how to build an MWRITER object, please refer to the MFILEWRITER object in file mmio/mmio.c in the library sources.


[ Next: | Previous:Structure Reference | Up:Library Reference ]

Error Reference

The following errors are currently defined:

General Errors

MMERR_DYNAMIC_LINKING
This error occurs when a specific driver was requested, but the support shared library couldn't be loaded. Currently, the only drivers which can yield this error are the ALSA, EsounD and Ultra drivers.
MMERR_OPENING_FILE
This error occurs when a file can not be opened, either for read access from a xx_Loadxx function, or for write access from the disk writer drivers.
MMERR_OUT_OF_MEMORY
This error occurs when there is not enough virtual memory available to complete the operation, or there is enough memory but the calling process would exceed its memory limit. MikMod does not do any resource tuning, your program has to use the setrlimit function to do this if it needs to load very huge samples.

Sample Errors

MMERR_SAMPLE_TOO_BIG
This error occurs when the memory allocation of the sample data yields the error MMERR_OUT_OF_MEMORY.
MMERR_OUT_OF_HANDLES
This error occurs when your program reaches the limit of loaded samples, currently defined as 384, which should be sufficient for most cases.
MMERR_UNKNOWN_WAVE_TYPE
This error occurs when you're trying to load a sample which format is not recognized.

Module Errors

MMERR_ITPACK_INVALID_DATA
This error occurs when a compressed module sample is corrupt.
MMERR_LOADING_HEADER
This error occurs when you're trying to load a module which has a corrupted header, or is truncated.
MMERR_LOADING_PATTERN
This error occurs when you're trying to load a module which has corrupted pattern data, or is truncated.
MMERR_LOADING_SAMPLEINFO
This error occurs when you're trying to load a module which has corrupted sample information, or is truncated.
MMERR_LOADING_TRACK
This error occurs when you're trying to load a module which has corrupted track data, or is truncated.
MMERR_MED_SYNTHSAMPLES
This error occurs when you're trying to load a MED module which has synthsounds samples, which are currently not supported.3
MMERR_NOT_A_MODULE
This error occurs when you're trying to load a module which format is not recognized.
MMERR_NOT_A_STREAM
This error occurs when you're trying to load a sample with a sample which format is not recognized.

Driver Errors

Generic Driver Errors

MMERR_16BIT_ONLY
This error occurs when the sound device doesn't support non-16 bit linear sound output, which are the requested settings.
MMERR_DETECTING_DEVICE
This error occurs when the driver's sound device has not been detected.
MMERR_INITIALIZING_MIXER
This error occurs when MikMod's internal software mixer could not be initialized properly.
MMERR_INVALID_DEVICE
This error occurs when the driver number (in md_device) is out of range.
MMERR_NON_BLOCK
This error occurs when the driver is unable to set the audio device in non blocking mode.
MMERR_OPENING_AUDIO
This error occurs when the driver can not open sound device.
MMERR_STEREO_ONLY
This error occurs when the sound device doesn't support mono sound output, which is the requested setting.

AudioFile Driver Specific Error

MMERR_AF_AUDIO_PORT
This error occurs when the AudioFile driver can not find a suitable AudioFile port.

AIX Driver Specific Errors

MMERR_AIX_CONFIG_CONTROL
This error occurs when the "Control" step of the device configuration has failed.
MMERR_AIX_CONFIG_INIT
This error occurs when the "Init" step of the device configuration has failed.
MMERR_AIX_CONFIG_START
This error occurs when the "Start" step of the device configuration has failed.

Ultra Driver Specific Errors

MMERR_GUS_RESET
This error occurs when the sound device couldn't be reset.
MMERR_GUS_SETTINGS
This error occurs because the sound device only works in 16 bit linear stereo sound at 44100 Hz, which is not the requested settings.
MMERR_GUS_TIMER
This error occurs when the ultra driver could not setup the playback timer.

HP-UX Driver Specific Errors

MMERR_HP_AUDIO_DESC
This error occurs when the HP driver can not get the audio hardware description.
MMERR_HP_AUDIO_OUTPUT
This error occurs when the HP driver can not select the audio output.
MMERR_HP_BUFFERSIZE
This error occurs when the HP driver can not set the transmission buffer size.
MMERR_HP_CHANNELS
This error occurs when the HP driver can not set the requested number of channels.
MMERR_HP_SETSAMPLESIZE
This error occurs when the HP driver can not set the requested sample size.
MMERR_HP_SETSPEED
This error occurs when the HP driver can not set the requested sample rate.

Open Sound System Driver Specific Errors

MMERR_OSS_SETFRAGMENT
This error occurs when the OSS driver can not set audio fragment size.
MMERR_OSS_SETSAMPLESIZE
This error occurs when the OSS driver can not set the requested sample size.
MMERR_OSS_SETSPEED
This error occurs when the OSS driver can not set the requested sample rate.
MMERR_OSS_SETSTEREO
This error occurs when the OSS driver can not set the requested number of channels.

SGI Driver Specific Errors

MMERR_SGI_MONO
This error occurs when the hardware only supports stereo sound.
MMERR_SGI_SPEED
This error occurs when the hardware does not support the requested sample rate.
MMERR_SGI_STEREO
This error occurs when the hardware only supports mono sound.
MMERR_SGI_16BIT
This error occurs when the hardware only supports 16 bit sound.
MMERR_SGI_8BIT
This error occurs when the hardware only supports 8 bit sound.

Sun Driver Specific Errors

MMERR_SUN_INIT
This error occurs when the sound device initialization failed.
MMERR_SUN_16BIT_ULAW
This error occurs when you're trying to use mu-law encoding with 16 bit sound.

OS/2 Driver Specific Errors

MMERR_OS2_MIXSETUP
This error occurs when the DART driver can not set the mixing parameters.
MMERR_OS2_SEMAPHORE
This error occurs when the MMPM/2 driver can not create the semaphores needed for playback.
<MMERR_OS2_THREAD
This error occurs when the MMPM/2 driver can not create the thread needed for playback.
MMERR_OS2_TIMER
This error occurs when the MMPM/2 driver can not create the timer needed for playback.

DirectX Driver Specific Errors

MMERR_DS_BUFFER
This error occurs when the DirectX driver can not allocate the playback buffers.
MMERR_DS_EVENT
This error occurs when the DirectX driver can not register the playback event.
MMERR_DS_FORMAT
This error occurs when the DirectX driver can not set the playback format.
MMERR_DS_NOTIFY
This error occurs when the DirectX driver can not register the playback callback.
MMERR_DS_PRIORITY
This error occurs when the DirectX driver can not set the playback priority.
MMERR_DS_THREAD
This error occurs when the DirectX driver can not create the playback thread.
MMERR_DS_UPDATE
This error occurs when the DirectX driver can not initialize the playback thread.

Windows Multimedia API Driver Specific Errors

MMERR_WINMM_ALLOCATED
This error occurs when the playback resource is already allocated by another application.
MMERR_WINMM_DEVICEID
This error occurs when the Multimedia API Driver is given an invalid audio device identificator.
MMERR_WINMM_FORMAT
This error occurs when the playback output format is not supported by the audio device.
MMERR_WINMM_HANDLE
This error occurs when the Multimedia API Driver is given an invalid handle.
MMERR_WINMM_UNKNOWN
This error should not occur !

MacOS Driver Specific Errors

MMERR_MAC_SPEED
This error occurs when the playback speed is not supported by the audio device.
MMERR_MAC_START
This error occurs when the MacOS driver can not start playback.


[ Next: | Previous:Error Reference | Up:Library Reference ]

Function Reference


[ Next: | Previous:Function Reference | Up:Function Reference ]

Library Core Functions

MikMod_Active

BOOL MikMod_Active(void)

Description
This function returns whether sound output is enabled or not.
Result
0
Sound output is disabled.
1
Sound output is enabled.
Notes
Calls to MikMod_Update will be ignored when sound output is disabled.
See also
MikMod_DisableOutput, MikMod_EnableOutput.

MikMod_DisableOutput

void MikMod_DisableOutput(void)

Description
This function stops the sound mixing.
Notes
Calls to MikMod_Update will be ignored when sound output is disabled.
See also
MikMod_Active, MikMod_EnableOutput.

MikMod_EnableOutput

BOOL MikMod_EnableOutput(void)

Description
This function starts the sound mixing.
Result
0
Sound mixing is ready.
nonzero
An error occurred during the operation.
Notes
Calls to MikMod_Update will be ignored when sound output is disabled.
See also
MikMod_Active, MikMod_DisableOutput.

MikMod_Exit

void MikMod_Exit(void)

Description
This function deinitializes the sound hardware and frees all the memory and resources used by MikMod.
See also
MikMod_Init, MikMod_Reset.

MikMod_GetVersion

long MikMod_GetVersion(void)

Description
This function returns the version number of the library.
Result
The version number, encoded as follows: (maj<<16)|(min<<8)|(rev), where maj is the major version number, min is the minor version number, and rev is the revision number.

MikMod_InfoDriver

CHAR* MikMod_InfoDriver(void)

Description
This function returns a formatted list of the registered drivers in a buffer.
Result
A pointer to a text buffer, or NULL if no drivers are registered.
Notes
The buffer is created with malloc; the caller must free it when it is no longer necessary.
See also
MikMod_RegisterDriver, MikMod_RegisterAllDrivers.

MikMod_InfoLoader

CHAR* MikMod_InfoLoader(void)

Description
This function returns a formatted list of the registered module loaders in a buffer.
Result
A pointer to a text buffer, or NULL if no loaders are registered.
Notes
The buffer is created with malloc; the caller must free it when it is no longer necessary.
See also
MikMod_RegisterLoader, MikMod_RegisterAllLoaders.

MikMod_Init

BOOL MikMod_Init(CHAR *parameters)

Description
This function performs the library initialization, including the sound driver choice and configuration, and all the necessary memory allocations.
Parameters
parameters
Optional parameters given to the sound driver. These parameters are ignored if the value of md_device is zero (autodetection).
Result
0
Initialization was successful.
nonzero
An error occurred during initialization.
Notes
When the initialization fails, the library uses the nosound sound driver to let other the other MikMod functions work without crashing the application.
See also
MikMod_Exit, MikMod_InitThreads, MikMod_Reset.

MikMod_InitThreads

BOOL MikMod_InitThreads(void)

Description
This function returns whether libmikmod is thread-safe.
Result
0
The library is not thread-safe.
1
The library is thread-safe.
Notes
This function should be called before any call to MikMod_Lock or MikMod_Unlock is made.
See also
MikMod_Lock, MikMod_Unlock.

MikMod_Lock

void MikMod_Lock(void)

Description
This function obtains exclusive access to libmikmod's variables.
Notes
This function locks an internal mutex. If the mutex is already locked, it will block the calling thread until the mutex is unlocked.
Every MikMod_Unlock call should be associated to a MikMod_Lock call. To be sure this is the case, we advise you to define and use the following macros:
#define MIKMOD_LOCK MikMod_Lock();{
#define MIKMOD_UNLOCK }MikMod_Unlock();
The function MikMod_InitThreads must have been invoked before any call to MikMod_Lock in made.

See also
MikMod_InitThreads, MikMod_Unlock.

MikMod_RegisterAllDrivers

void MikMod_RegisterAllDrivers(void)

Description
This function registers all the available drivers.
See also
MikMod_InfoDriver, MikMod_RegisterDriver.

MikMod_RegisterAllLoaders

void MikMod_RegisterAllLoaders(void)

Description
This function registers all the available module loaders.
See also
MikMod_InfoLoader, MikMod_RegisterLoader.

MikMod_RegisterDriver

void MikMod_RegisterDriver(struct MDRIVER* newdriver)

Description
This function adds the specified driver to the internal list of usable drivers.
Parameters
newdriver
A pointer to the MDRIVER structure identifying the driver.
Notes
It is safe to register the same driver several times, although it will not be duplicated in the list.
You should register all the drivers you need before calling MikMod_Init. If you want to register all the available drivers, use MikMod_RegisterAllDrivers instead.
See also
MikMod_InfoDriver, MikMod_RegisterAllDrivers.

MikMod_RegisterErrorHandler

MikMood_handler_t MikMod_RegisterErrorHandler(MikMod_handler_t newhandler)

Description
This function selects the function which should be called in case of error.
Parameters
newhandler
The new error callback function.
Result
The previous error callback function, or NULL if there was none.
Notes
MikMod_handler_t is defined as void(*function)(void), this means your error function has the following prototype: void MyErrorHandler(void)
The error callback function is called when errors are detected, but not always immediately (the library has to resume to a stable state before calling your callback).

MikMod_RegisterLoader

void MikMod_RegisterLoader(struct MLOADER* newloader)

Description
This function adds the specified module loader to the internal list of usable module loaders.
Parameters
newloader
A pointer to the MLOADER structure identifying the loader.
Notes
It is safe to register the same loader several times, although it will not be duplicated in the list.
You should register all the loaders you need before calling Player_Load or Player_LoadFP. If you want to register all the available module loaders, use MikMod_RegisterAllLoaders instead.
The 15 instrument module loader (load_m15) should always be registered last.
See also
MikMod_InfoLoader, MikMod_RegisterAllLoaders.

MikMod_RegisterPlayer

MikMod_player_t MikMod_RegisterPlayer(MikMod_player_t newplayer)

Description
This function selects the function which should be used to process module playback.
Parameters
newplayer
The new playback function
Result
The previous playback function.
Notes
MikMod_player_t is defined as void(*function)(void), this means your player function has the following prototype: void MyPlayer(void)
The player function is called every module tick to process module playback. The rate at which the player function is called is controlled by the sound driver, and is computed by the following equation:
(bpm*50)/125 calls per second, which means every 125000/(bpm*50) milliseconds. The bpm value is the tempo of the module and can change from its initial value when requested by the module.
When changing the playback function, you should make sure that you chain to the default MikMod playback function, otherwise you won't get module sound anymore....
Example
    MikMod_player_t oldroutine;

    void MyPlayer(void)
    {
        oldroutine();
        /* your stuff here */
        ...
    }

    main()
    {
        ...
        /* Register our player */
        oldroutine=MikMod_RegisterPlayer(MyPlayer);
        ...
    }

MikMod_Reset

BOOL MikMod_Reset(CHAR *parameters)

Description
This function resets MikMod and reinitialize the sound hardware.
Parameters
parameters
Optional parameters given to the sound driver. If you set the value of md_device to zero (autodetect), these parameters are ignored.
Result
0
Reinitialization was successful.
nonzero
An error occurred during reinitialization.
Notes
Use this function when you have changed the global configuration variables: md_device and md_mixfreq, or one of the md_mode flags which require sound reinitialization. Sound playback will continue as soon as the driver is ready.
See also
MikMod_Exit, MikMod_Init.

MikMod_SetNumVoices

BOOL MikMod_SetNumVoices(int musicvoices,int samplevoices)

Description
This function sets the number of mixed voices which can be used for music and sound effects playback.
Parameters
musicvoices
The number of voices to reserve for music playback.
samplevoices
The number of voices to reserve for sound effects.
Result
0
Initialization was successful.
nonzero
An error occurred during initialization.
Notes
A value of -1 for any of the parameters will retain the current number of reserved voices.
The maximum number of voices vary from driver to driver (hardware drivers often have a limit of 32 to 64 voices, whereas the software drivers handle 255 voices). If your settings exceed the driver's limit, they will be truncated.
See also
MikMod_Init, MikMod_Reset.

MikMod_Unlock

void MikMod_Unlock(void)

Description
This function relinquishes exclusive access to libmikmod's variables.
Notes
This function unlocks an internal mutex, so that other threads waiting for the lock can be resumed.
Every MikMod_Unlock call should be associated to a MikMod_Lock call. To be sure this is the case, we advise you to define and use the following macros:
#define MIKMOD_LOCK MikMod_Lock();{
#define MIKMOD_UNLOCK }MikMod_Unlock();
The function MikMod_InitThreads must have been invoked before any call to MikMod_Unlock in made.

See also
MikMod_InitThreads, MikMod_Lock.

MikMod_Update

void MikMod_Update(void)

Description
This routine should be called on a regular basis to update the sound.
Notes
The sound output buffer is filled each time this function is called; if you use a large buffer, you don't need to call this routine as frequently as with a smaller buffer, but you get a bigger shift between the sound being played and the reported state of the player, since the player is always a buffer ahead of the playback.
If you play low quality sound (for example, mono 8 bit 11kHz sound), you only need to call this routine a few times per second. However, for high quality sound (stereo 16 bit 44kHz), this rate increases to a few hundred times per second, but never more, due to the minimal buffer size constraint imposed to the sound drivers.
If you plan on modifying voice information with the Voice_xx functions, you should do this before calling MikMod_Update.

MikMod_strerror

char* MikMod_strerror(int errno)

Description
This function associates a descriptive message to an error code.
Parameters
errno
The MikMod error code.
Result
A pointer to a string describing the error.


[ Next: | Previous:Library Core Functions | Up:Function Reference ]

Module Player Functions

Player_Active

BOOL Player_Active(void)

Description
This function returns whether the module player is active or not.
Result
0
No module is playing.
nonzero
A module is currently playing.
Notes
This function will still report that the player is active if the playing module is paused.
See also
Player_Paused, Player_TogglePause, Player_Start, Player_Stop

Player_Free

void Player_Free(MODULE* module)

Description
This function stops the module if it is playing and unloads it from memory.
Parameters
module
The module to free.
See also
Player_Load, Player_LoadFP.

Player_GetChannelVoice

int Player_GetChannelVoice(UBYTE channel)

Description
This function determines the voice corresponding to the specified module channel.
Parameters
channel
The module channel to use.
Result
The number of the voice corresponding to the module channel.
Notes
If the module channel has NNAs, the number will correspond to the main channel voice.
See also
Voice_SetPanning, Voice_SetVolume, Player_Mute, Player_ToggleMute, Player_Unmute.

Player_GetModule

MODULE* Player_GetModule(void)

Description
This function returns the module currently being played.
Result
A pointer to the MODULE being played, or NULL if no module is playing.
See also
Player_Stop, Player_Start.

Player_Load

MODULE* Player_Load(CHAR* filename,int maxchan,BOOL curious)

Description
This function loads a music module.
Parameters
filename
The name of the module file.
maxchan
The maximum number of channels the song is allowed to request from the mixer.
curious
The curiosity level to use.
Result
A pointer to a MODULE structurre, or NULL if an error occurs.
Notes
If the curiosity level is set to zero, the module will be loaded normally. However, if it is nonzero, the following things occur:
See also
Player_Free, Player_LoadFP, Player_LoadTitle, Player_Start.

Player_LoadFP

MODULE* Player_LoadFP(FILE* file,int maxchan,BOOL curious)

Description
This function loads a music module.
Parameters
file
An open file, at the position where the module starts.
maxchan
The maximum number of channels the song is allowed to request from the mixer.
curious
The curiosity level to use.
Result
A pointer to a MODULE structure, or NULL if an error occurs.
Notes
The file is left open, at the same position as before the function call.
If the curiosity level is set to zero, the module will be loaded normally. However, if it is nonzero, the following things occur:
See also
Player_Free, Player_Load, Player_LoadTitle, Player_Start.

Player_LoadTitle

MODULE* Player_LoadTitle(CHAR* filename)

Description
This function retrieves the title of a module file.
Parameters
filename
The name of the module file.
Result
A pointer to the song title, or NULL if either the module has no title or an error has occurred.
Notes
The title buffer is created with malloc; the caller must free it when it is no longer necessary.
See also
Player_Load, Player_LoadFP.

Player_Mute

void Player_Mute(SLONG operation,...)

Description
This function mutes a single module channel, or a range of module channels.
Parameters
operation
Either the number of a module channel to mute (starting from zero), or an operation code. In the latter case, two extra parameters are needed to determine the range of channels.
Notes
If the operation is MUTE_INCLUSIVE, the two channel numbers delimit the range and are part of the range ; otherwise, if the operation is MUTE_EXCLUSIVE, they are outside of the range.
Example
    /* mute channel 10 */
    Player_Mute(10);
    /* mute channels 2 to 5 */
    Player_Mute(MUTE_INCLUSIVE,2,5);
    /* mute channels 7 to 9 */
    Player_Mute(MUTE_EXCLUSIVE,6,10);

See also
Player_Muted, Player_ToggleMute, Player_Unmute.

Player_Muted

BOOL Player_Muted(UBYTE channel)

Description
This function determines whether a module channel is muted or not.
Parameters
channel
The module channel to test (starting from zero).
Result
0
The channel is not muted.
1
The channel is muted.
See also
Player_Mute, Player_ToggleMute, Player_Unmute.

Player_NextPosition

void Player_NextPosition(void)

Description
This function jumps to the next position in the module.
Notes
All playing samples and active song voices are cut to avoid hanging notes.
See also
Player_PrevPosition, Player_SetPosition.

Player_Paused

BOOL Player_Paused(void)

Description
This function determines whether the module is paused or not.
Result
0
The module is not paused.
1
The module is paused.
See also
Player_TogglePause.

Player_PrevPosition

void Player_PrevPosition(void)

Description
This function jumps to the previous position in the module.
Notes
All playing samples and active song voices are cut to avoid hanging notes.
See also
Player_NextPosition, Player_SetPosition.

Player_SetPosition

void Player_SetPosition(UWORD position)

Description
This function jumps to the specified position in the module.
Parameters
position
The pattern position to jump to.
Notes
All playing samples and active song voices are cut to avoid hanging notes.
See also
Player_NextPosition, Player_PrevPosition.

Player_SetSpeed

void Player_SetSpeed(UWORD speed)

Description
This function sets the module speed.
Parameters
speed
The new module speed, in the range 1-32.
See also
Player_SetTempo.

Player_SetTempo

void Player_SetTempo(UWORD tempo)

Description
This function sets the module tempo.
Parameters
tempo
The new module tempo, in the range 32-255.
See also
Player_SetSpeed.

Player_SetVolume

void Player_SetVolume(SWORD volume)

Description
This function sets the module volume.
Parameters
volume
The new overall module playback volume, in the range 0-128.

Player_Start

void Player_Start(MODULE* module)

Description
This function starts the specified module playback.
Parameters
module
The module to play.
Notes
If another module is playing, it will be stopped and the new module will play.
See also
Player_Stop.

Player_Stop

void Player_Stop(void)

Description
This function stops the currently playing module.
See also
Player_Start.

Player_ToggleMute

void Player_ToggleMute(SLONG operation,...)

Description
This function changes the muted status of a single module channel, or a range of module channels.
Parameters
operation
Either the number of a module channel to work on (starting from zero), or an operation code. In the latter case, two extra parameters are needed to determine the range of channels.
Notes
If the operation is MUTE_INCLUSIVE, the two channel numbers delimit the range and are part of the range ; otherwise, if the operation is MUTE_EXCLUSIVE, they are outside of the range.
Example
    /* toggle mute on channel 10 */
    Player_ToggleMute(10);
    /* toggle mute on channels 2 to 5 */
    Player_ToggleMute(MUTE_INCLUSIVE,2,5);
    /* toggle mute on channels 7 to 9 */
    Player_ToggleMute(MUTE_EXCLUSIVE,6,10);

See also
Player_Mute, Player_Muted, Player_Unmute.

Player_TogglePause

void Player_TogglePause(void)

Description
This function toggles the playing/paused status of the module.
Notes
Calls to Player_xx functions still have effect when the module is paused.
See also
Player_Paused, Player_Start, Player_Stop.

Player_Unmute

void Player_Unmute(SLONG operation,...)

Description
This function unmutes a single module channel, or a range of module channels.
Parameters
operation
Either the number of a module channel to unmute (starting from zero), or an operation code. In the latter case, two extra parameters are needed to determine the range of channels.
Notes
If the operation is MUTE_INCLUSIVE, the two channel numbers delimit the range and are part of the range ; otherwise, if the operation is MUTE_EXCLUSIVE, they are outside of the range.
Example
    /* unmute channel 10 */
    Player_Unmute(10);
    /* unmute channels 2 to 5 */
    Player_Unmute(MUTE_INCLUSIVE,2,5);
    /* unmute channels 7 to 9 */
    Player_Unmute(MUTE_EXCLUSIVE,6,10);

See also
Player_Mute, Player_Muted, Player_ToggleMute.


[ Next: | Previous:Module Player Functions | Up:Function Reference ]

Sample Functions

Sample_Free

void Sample_Free(SAMPLE* sample)

Description
This function unloads a sample from memory.
Parameters
sample
The sample to free.
See also
Sample_Load, Sample_LoadFP.

Sample_Load

SAMPLE* Sample_Load(CHAR* filename)

Description
This function loads a sample.
Parameters
filename
The sample filename.
Result
A pointer to a SAMPLE structure, or NULL if an error has occurred.
See also
Sample_Free, Sample_LoadFP.

Sample_LoadFP

SAMPLE* Sample_LoadFP(FILE* file)

Description
This function loads a sample.
Parameters
file
An open file, at the position where the sample starts.
Result
A pointer to a SAMPLE structure, or NULL if an error has occurred.
Notes
The file is left open, at the same position as before the function call.
See also
Sample_Free, Sample_Load.

Sample_Play

SBYTE Sample_Play(SAMPLE* sample,ULONG start,UBYTE flags)

Description
This function plays a sample as a sound effect.
Parameters
sample
The sample to play.
start
The starting position (in samples).
flags
Either zero, for normal sound effects, or SFX_CRITICAL, for critical sound effects which must not be interrupted.
Result
The voice number corresponding to the voice which will play the sample.
Notes
Each new sound effect is played on a new voice. When all voices are taken, the oldest sample which was not marked as critical is cut and its voice is used for the new sample. Critical samples are not cut unless all the voices are taken with critical samples and you attempt to play yet another critical sample. Use Voice_Stop to force the end of a critical sample.
See also
MikMod_SetNumVoices, Voice_Play, Voice_SetFrequency, Voice_SetPanning, Voice_SetVolume, Voice_Stop.


[ Next: | Previous:Sample Functions | Up:Function Reference ]

Voice Functions

Voice_GetFrequency

ULONG Voice_GetFrequency(SBYTE voice)

Description
This function returns the frequency of the sample currently playing on the specified voice.
Parameters
voice
The number of the voice to get frequency.
Result
The current frequency of the sample playing on the specified voice, or zero if no sample is currently playing on the voice.
See also
Voice_SetFrequency.

Voice_GetPanning

ULONG Voice_GetPanning(SBYTE voice)

Description
This function returns the panning position of the sample currently playing on the specified voice.
Parameters
voice
The number of the voice to get panning position.
Result
The current panning position of the sample playing on the specified voice, or PAN_CENTER if no sample is currently playing on the voice.
See also
Voice_SetPanning.

Voice_GetPosition

SLONG Voice_GetPosition(SBYTE voice)

Description
This function returns the sample position (in samples) of the sample currently playing on the specified voice.
Parameters
voice
The number of the voice to get sample position (starting from zero).
Result
The current play location of the sample playing on the specified voice, or zero if the position can not be determined or if no sample is currently playing on the voice.
Notes
This function may not work with some drivers (especially for hardware mixed voices). In this case, it returns always -1.
See also
Sample_Play, Voice_Play.

Voice_GetVolume

UWORD Voice_GetVolume(SBYTE voice)

Description
This function returns the volume of the sample currently playing on the specified voice.
Parameters
voice
The number of the voice to get volume.
Result
The current volume of the sample playing on the specified voice, or zero if no sample is currently playing on the voice.
See also
Voice_RealVolume, Voice_SetVolume.

Voice_Play

void Voice_Play(SBYTE voice,SAMPLE* sample,ULONG start)

Description
Start a new sample in the specified voice.
Parameters
voice
The number of the voice to be processed (starting from zero).
sample
The sample to play.
start
The starting position (in samples).
Notes
The sample will be played at the volume, panning and frequency settings of the voice, regardless or the sample characteristics.
The sample played this way gets the same "critical" status as the sample which was previously played on this voice.
See also
Sample_Play, Voice_SetFrequency, Voice_SetPanning, Voice_SetVolume.

Voice_RealVolume

ULONG Voice_RealVolume(SBYTE voice)

Description
This function returns the actual playing volume of the specified voice.
Parameters
voice
The number of the voice to analyze (starting from zero).
Result
The real volume of the voice when the function was called, in the range 0-65535, not related to the volume constraint specified with Voice_SetVolume.
Notes
This function may not work with some drivers (especially for hardware mixed voices). In this case, it always returns zero.
Also note that the real volume computation is not a trivial process and takes some CPU time.
See also
Sample_Play, Voice_GetVolume, Voice_Play, Voice_SetVolume.

Voice_SetFrequency

void Voice_SetFrequency(SBYTE voice,ULONG frequency)

Description
This function sets the frequency (pitch) of the specified voice.
Parameters
voice
The number of the voice to be processed (starting from zero).
frequency
The new frequency of the voice, in hertz.
See also
Sample_Play, Voice_GetFrequency, Voice_Play, Voice_SetPanning, Voice_SetVolume, Voice_Stop.

Voice_SetPanning

void Voice_SetPanning(SBYTE voice,ULONG panning)

Description
This function sets the panning position of the specified voice.
Parameters
voice
The number of the voice to be processed (starting from zero).
panning
The new panning position of the voice.
Notes
Panning can vary between 0 (PAN_LEFT) and 255 (PAN_RIGHT). Center is 127 (PAN_CENTER. Surround sound can be enabled by specifying the special value PAN_SURROUND.
See also
Sample_Play, Voice_GetPanning, Voice_Play, Voice_SetFrequency, Voice_SetVolume, Voice_Stop.

Voice_SetVolume

void Voice_SetVolume(SBYTE voice,UWORD volume)

Description
This function sets the volume of the specified voice.
Parameters
voice
The number of the voice to be processed (starting from zero).
volume
The new volume of the voice, in the range 0-256.
See also
Sample_Play, Voice_GetVolume, Voice_Play, Voice_SetFrequency, Voice_SetPanning, Voice_Stop.

Voice_Stop

void Voice_Stop(SBYTE voice)

Description
This function stops the playing sample of the specified voice.
Parameters
voice
The number of the voice to be processed (starting from zero).
Notes
After the call to Voice_Stop, the function Voice_Stopped will return nonzero (true) for the voice. If you want to silence the voice without stopping the playback, use Voice_SetVolume(voice,0) instead.
See also
Sample_Play, Voice_Play, Voice_SetFrequency, Voice_SetPanning, Voice_SetVolume.

Voice_Stopped

BOOL Voice_Stopped(SBYTE voice)

Description
This function returns whether the voice is active or not.
Parameters
voice
The number of the voice to be checked (sttarting from zero).
Result
0
The voice is stopped or has no sample assigned.
nonzero
The voice is playing a sample.
Notes
This function may not work with some drivers (especially for hardware mixed voices). In this case, its return value is undefined.
See also
Voice_Stop.


[ Next: | Previous:Voice Functions | Up:Library Reference ]

Loader Reference


[ Next: | Previous:Loader Reference | Up:Loader Reference ]

Module Loaders

MikMod presents a large choice of module loaders, for the most common formats as well as for some less-known exotic formats.

load_669
This loader recognizes "Composer 669" and "Unis 669" modules. The 669 and "Extended 669" formats were among the first PC module formats. They do not have a wide range of effects, but support up to 32 channels.
"Composer 669" was written by Tran of Renaissance, a.k.a. Tomasz Pytel and released in 1992. "Unis 669 Composer" was written by Jason Nunn and released in 1994.
load_amf
This loader recognizes the "Advanced Module Format", which is the internal module format of the "DOS Sound and Music Interface" (DSMI) library. This format has the same limitations as the S3M format. The most famous DSMI application was DMP, the Dual Module Player.
DMP and the DSMI library were written by Otto Chrons. DSMI was first released in 1993.
load_dsm
This loader recognizes the internal DSIK format, which is the internal module format of the "Digital Sound Interface Kit" (DSIK) library, the ancester of the SEAL library. This format has the same limitations as the S3M format.
The DSIK library was written by Carlos Hasan and released in 1994.
load_far
This loader recognizes "Farandole" modules. These modules can be up to 16 channels and have Protracker comparable effects.
The Farandole composer was written by Daniel Potter and released in 1994.
load_gdm
This loader recognizes the "General DigiMusic" format, which is the internal format of the "Bells, Whistles and Sound Boards" library. This format has the same limitations as the S3M format.
The BWSB library was written by Edward Schlunder and first released in 1993.
load_imf
This loader recognizes "Imago Orpheus" modules. This format is roughly equivalent to the XM format, but with two effects columns instead of a volume column and an effect column.
Imago Orpheus was written by Lutz Roeder and released in 1994.
load_it
This loader recognizes "Impulse Tracker" modules, currently the most powerful format. These modules support up to 64 real channels, and up to 256 virtual channels with the "New Note Action" feature. Besides, it has the widest range of effects, and supports 16 bit samples as well as surround sound.
"Impulse Tracker" was written by Jeffrey Lim and released in 1996.
load_med
This loader recognizes "OctaMED" modules. These modules are comparable to Protracker modules, but can embed "synthsounds", which are midi-like instruments.
"MED" and later "OctaMED" were written by Teijo Kinnunen. "MED" was released in 1989, and "OctaMED" was released in 1992.
load_m15
This loader recognizes the old 15 instrument modules, created by "Ultimate Soundtracker", "Soundtracker" and the first versions of "Protracker".
Since this format was one of the first module formats, developed in 1987, it does not have any signature field, which makes it hard to detect reliably, because of its similarities with later module formats.
load_mod
This loader recognizes the standard 31 instrument modules, created by "Protracker" or Protracker-compatible programs. The original Protracker format was limited to 4 channels, but other trackers like "TakeTracker", "StarTracker" or "Oktalyzer" afforded more channels.
Although it is now technically obsolete, this format is still widely used, due to its playback simplicity (on the adequate hardware, the Amiga).
load_mtm
This loader recognizes the "MultiTracker Module Editor" modules. The MTM format has up to 32 channels, and protracker comparable effects. It was intended to replace "Composer 669". The "MultiTracker Module Editor" was written by Starscream of Renaissance, a.k.a. Daniel Goldstein and released in late 1993.
load_stm
This loader recognizes "ScreamTracker" modules. "ScreamTracker" was the first PC tracker, as well as the first PC module format. Loosely inspired by the "SoundTracker" format, it does not have as many effects as Protracker, although it supports 31 instruments and 4 channels.
"ScreamTracker" was written by PSI of Future Crew, a.k.a. Sami Tammilehto.
load_stx
This loader recognizes "STMIK 0.2" modules. "STMIK" (the Scream Tracker Music Interface Kit) was a module playing library distributed by Future Crew to play Scream Tracker module in games and demos. It uses an intermediate format between STM and S3M and comes with a tool converting STM modules to STX.
"STMIK" was written by PSI of Future Crew, a.k.a. Sami Tammilehto.
load_s3m
This loader recognizes "ScreamTracker 3" modules. This version was a huge improvement over the original "ScreamTracker". It supported 32 channels (although the tracker only let you work on 16), up to 99 instruments, and a large choice of effects.
"ScreamTracker 3" was written by PSI of Future Crew, a.k.a. Sami Tammilehto, and released in 1994.
load_ult
This loader recognizes "UltraTracker" modules. They are mostly similar to Protracker modules, but support two effects per channel.
"UltraTracker" was written by MAS of Prophecy, a.k.a. Marc Andre Schallehn, and released in 1993.
load_uni
This loader recognizes "UNIMOD" modules. This is the internal format used by MikMod and APlayer. Use of this format is discouraged, this loader being provided for completeness.
load_xm
This loader recognizes "FastTracker 2" modules. This format was designed from scratch, instead of creating yet another Protracker variation. It was the first format using instruments as well as samples, and envelopes for finer effects.
FastTracker 2 was written by Fredrik Huss and Magnus Hogdahl, and released in 1994.


[ Next: | Previous:Module Loaders | Up:Loader Reference ]

Sample Loaders

Currently, the only file type than can be loaded as a sample is the RIFF WAVE file. Stereo or compressed WAVE files are not supported yet.


[ Next: | Previous:Sample Loaders | Up:Library Reference ]

Driver Reference


[ Next: | Previous:Driver Reference | Up:Driver Reference ]

Network Drivers

These drivers send the generated sound over the network to a server program, which sends the sound to the real sound hardware. The server program can be on the same machine than your program, but MikMod does not have access to the hardware. Network drivers only support software mixing.

drv_AF
This driver works with the "Digital AudioFile" library.
Start the server on the machine you want, set its hostname in the AUDIOFILE environment variable, and MikMod is ready to send it sound.
drv_esd
This driver works with the "Enlightened Sound Daemon".
Start the esd daemon on the machine you want, set its hostname in the ESPEAKER environment variable, and MikMod is ready to send it sound.


[ Next: | Previous:Network Drivers | Up:Driver Reference ]

Hardware Drivers

These drivers access to the sound hardware of the machine they run on. Depending on your Unix flavor, you'll end with one or more drivers from this list:

drv_aix
This driver is only available under AIX, and access its audio device.
This driver only supports software mixing.
drv_alsa
This driver is only available under Linux, and requires the ALSA driver to be compiled for your kernel version.
This driver only supports software mixing, but a future version of the driver might be able to use the hardware capabilities of some sound cards.
drv_dart
This driver is only available under OS/2 version 3 and higher (Warp), and uses the "Direct Audio RReal-Time" interface.
This driver only supports software mixing.
drv_hp
This driver is only available under HP-UX, and access its audio device.
This driver only supports software mixing.
drv_os2
This driver is only available under OS/2 version 3 and higher (Warp), and OS/2 2.x with MMPM/2.
This driver only supports software mixing.
drv_oss
This driver is available under any Unix with the Open Sound System drivers installed. Linux and FreeBSD also come with the OSS/Lite driver (the non-commercial version of OSS) and can make use of this driver.
This driver only supports software mixing.
drv_sgi
This driver is only available under IRIX, and uses the SGI audio library.
This driver only supports software mixing.
drv_sun
This driver is only available under Unices which implement SunOS-like audio device interfaces, that is, SunOS, Solaris, NetBSD and OpenBSD.
This driver only supports software mixing.
drv_ultra
This driver is only available under Linux, and requires the Linux Ultrasound driver (the ancestor of ALSA) to be compiled for your kernel version.
This driver only supports hardware mixing.


[ Next: | Previous:Hardware Drivers | Up:Driver Reference ]

Disk Writer Drivers

These drivers work on any machine, since the generated sound is not sent to hardware, but written in a file. Disk writer drivers only support software mixing.

drv_raw
This driver outputs the sound date in a file by default named music.raw in the current directory. The file has no header and only contains the sound output.
drv_wav
This driver outputs the sound data in a RIFF WAVE file by default named music.wav in the current directory.


[ Previous:Disk Writer Drivers | Up:Driver Reference ]

Other Drivers

These drivers are of little interest, but are handy sometimes.

drv_stdout
This driver outputs the sound data to the program's standard output. To avoid inconvenience, the data will not be output if the standard output is a terminal, thus you have to pipe it through another command or to redirect it to a file. Using this driver and redirecting to a file is equivalent to using the drv_raw disk writer.
This driver only supports software mixing.
drv_pipe
This driver pipes the sound data to a command (which must be given in the driver commandline, via MikMod_Init).
This driver only supports software mixing.
drv_nos
This driver doesn't produce sound at all, and will work on any machine.
Since it does not have to produce sound, it supports both hardware and software mixing, with as many hardware voices as you like.


[ Next: | Previous:Library Reference | Up:Top ]

Index


[ Next: | Previous:Index | Up:Index ]

Function Index

Menu


[ Previous:Function Index | Up:Index ]

Type and Variable Index

Menu

Table of Contents


Footnotes

  1. PAN_SURROUND will be mapped to PAN_CENTER if the library is initialized without surround sound, that is, if the variable md_mode doesn't have the bit DMODE_SURROUND set.

  2. Unless you explicitely choose to create a non thread-safe version of libmikmod at compile-time.

  3. You can force libmikmod to load the module (without the synthsounds, of course) by setting the curious parameter to 1 when invoking Player_Loadxx.