Introduction to NAS(Network Audio System)
NAS(Network Audio System)入門

*contents
o 対象
o Disclaimer
o What's NAS
o 基本用語
o eventについて
o actionについて
o audio libraryの使い方
o 簡単な使い方
o 基本的な使い方
o advancedな使い方
o 録音等について
o examples
o Xtとの連携
o その他触れておくべき事
o NASの入手及びinstallの仕方
o 参考文献
o Contact

*対象
NASの入門です。
C++についての簡単な知識は仮定します。Cで使うには少しばかりの変更で
大丈夫でしょう。(iostream,変数の宣言を最初に持ってくる等。)
(Xでのプログラミングの知識があると助けになるでしょう。
と言うか無いとつらいかな?)
audio dataについての基本的な事は仮定します。
NASを用いて音が出せるようになって、ちょっとした制御が出来る様
になることを目標にします。
これを読めば後は大体manを見れば何とかなるという様になるのが理想です。
(録音等については解説しませんが、参考にはなるでしょう。
(単に使った事が無いだけですが…。))
NASについて網羅的に解説する事は目標ではありません。
(結果としてそうなってしまうかも知れませんが。)
しかし対象となる人っていったい何人くらいいるのだらう。殆んどいないような…。
もしいらしたら感想等聞かせて頂ければ幸いです。又、間違い等発見されましたら報せてください。
また、提案、意見その他も歓迎します。

*Discailmer
この文章は無保証です。この文書及び付属のsample programを利用した、
あるいは出来なかった、しなかったことによる結果に対する責任はいっさい負いません。
各自の責任で使用してください。


*What's NAS
NASとはNCDによって開発されたものでnetwork上でaudio dataを再生したり録音したり、その他色々な操作を行えるものです。
NASはXをお手本にしている様で、cilent server modelによっています。
Xと同様netowork透過です。

Application(client):NAS API----------network-----------------NAS Server

以下NASに付属のFAQからの引用。
>        Key features of the Network Audio System include:
>
>            o   Device-independent audio over the network
>            o   Lots of audio file and data formats
>            o   Can store sounds in server for rapid replay
>            o   Extensive mixing, separating, and manipulation of audio data
>            o   Simultaneous use of audio devices by multiple applications
>            o   Use by a growing number of ISVs
>            o   Small size
>            o   Free!  No obnoxious licensing terms

現在サーバーは以下のplathomeであるようです。(これもFAQからの引用。)
>            o Sun Sparc 1 AM79C30A Digital Subscriber Controller and
>                  Sparc 10 Dual Basic Rate ISDN Interface
>              (SunOS 4.1.[23], Solaris 2.x)
>
>            o SGI Indigo (IRIX 5.x)
>
>            o VOXware (FreeBSD, Linux, SVR4.[02])
>
>            o HPUX





note:manを見てみるとnot implementedとなっていたりする事があるので注意が必要です。

*基本用語
flow
flowとはclientが入力や出力やデータの操作をどの様にするか指定する物です。
具体的には次に示すelementの幾つかにより指定されます。
(この説明で良く分からなくても具体例でやってみれはすぐ分かると思います。)

element
dataの入力元やデータに行う操作やデータの出力先を示します。

component
elementのうちデータの入力元とデータの出力先になるものを特にcomponent
と呼びます。Stopped,Paused,Startedのstateがあります。(説明不要でしょう。)

elementとcomponentの例をあげます。
componentの例(当然elementでもあります。)
physical device(speaker,mic,cd等の音を再生するもの)
virtual device(sine wave,square wave,saw wave,constantがあります。
数学的に作り出す音です。)
bucket(データを貯めておくための物です。例えば頻繁に再生するデータをサーバー側に置いておいたり、録音したデータを一時的に保持しておくためのものです。)

elementの例(後で説明します。)
Monitor element(再生の状況を一報告します。)
add(一定数を加えます。)
sum(mixingに使います。)
bundle(trackをあわせます。)
multiply(一定数をかけます。これで音量調整をする事が出来ます。。)

*eventについて
何か変化があるとそれはEventという形でclientに通知されます。
eventについては次のものがあります。
AuEventTypeElementNotify:elementの状態が変化したときなどに通知されます。(再生が開始したとか再生が終了したとか。)
AuEventTypeGrabNotify
AuEventTypeMonitorNotify:monitor elementから通知されるイベント(?)
専ら使うのはNotify Eventでしょう。
例えばデータの再生が終了したといったことを知ることができます。

state
*actionについて
componentにactionを登録することができます。
具体的にはcomponentが指定した状態の変化があったときに特定の動作を
させるものです。(残念ながら関数が登録出来るわけではありません。)
これにより例えばデータをループさせて再生させるといった事が出来ます。

*audio libraryの使い方
HowToCompile
次のファイルをincludeしましょう。
#include <audio/audiolib.h>
link時には
-laudio  -lXau
を付け足しましょう。
又-L/usr/X11R6/libなどとXのlibrary pathを指定する必要があるでしょう。
(pathは環境によって適当に変えてください。)
(NASが通常と違う場所にinstallされているならばinclude path(-I)とlibrary path(-L)
を指定する必要があるでしょう。)
-lXauは接続のauthorizationに使うので必要となります。




*簡単な使い方
ここではサーバーに接続して、audio dataのファイルを再生します。
See elementary.cc

まずはサーバーとの接続
char** returnStatus=NULL;
AuServer auServer=AuOpenServer (NULL,0,NULL,0,NULL,returnStatus);
if (auServer==NULL)
{
        cout << returnStatus <<endl;
        exit (-1);
}
サーバーとの接続を開始します。
AuServer *AuOpenServer
(char *servername,
 int num_authproto,
 char *authproto,
 int num_authdata,
 char *authdata,
 char **return_status/* RETURN */)
いろいろ引数がありますが、何も考えずに
AuServer auServer=AuOpenServer (NULL,0,NULL,0,NULL,NULL);
でいいでしょう。で必要なら環境変数AUDIOSERVERを設定するようにしましょう。
(X上で起動した場合は設定されていなくても適当に選ばれるようです。)
接続に問題が起これば帰り値にNULLが返されます。


サーバーとの接続を終了します。処理が済んだらちゃんと終了処理をしましょう。
void AuCloseServer(AuServer *server)

通信のflushをします。
void AuFlush(AuServer *server)



AuFixedPoint 定数を表す物です。以下の物を使って作ります。
AuFixedPoint AuFixedPointFromFraction(int nnn,int ddd)
分数で表されます。nnn/dddとなります。
例えばnnn=vol,ddd=100とすると全体を100としたときのvolだけの音量になります。
AuFixedPoint AuFixedPointFromSum(int a,int b)
和で表されます。a.bとなる(?)
まぁ、特に音量を気にするのでなければ
AuFixedPointFromFraction(1,1)
または
AuFixedPointFromSum(1,0)
を使えばいいでしょう。

ほかにもFixedPointを扱うものとして以下の物があります。
(引数は書きません、必要ならmanを見てください。)
AuFixedPointFractionalAddend ()
AuFixedPointIntegralAddend ()
AuFixedPointRoundDown ()
AuFixedPointRoundUp ()


以下を使ってファイルやデータを再生します。
AuSoundPlayFormFile ()
AuSoundPlaySynchronousFromFile ()
AuSoundPlayFromData ()

取り敢えず以下のようにすれば音が出ます。
AuSoundPlayFromFile(server,filename,AuNone,
                    AuFixedPointFromFraction(volume, 100),
                    NULL,NULL,NULL,NULL,NULL,NULL)

詳しい解説
AuEventHandlerRec  *AuSoundPlayFromFile
(AuServer *server,
 char *filename,
 AuDeviceID destination,
 AuFixedPoint volume,
 void (*callback)(AuServer *,AuEventHandlerRec *,AuEvent *,AuPointer),
 AuPointer callback_data,
 AuFlowID *flow /* RETURN */,
 int *volume_mult_elem /* RETURN */,
 int *monitor_element /* RETURN */,
 AuStatus *status /* RETURN */)

filenameで指定されたデータを再生します。これはブロックはされないようなので
必要ならイベントを使って再生が終了をしたことを知る必要があります。
(再生の途中でプログラムが終了してしまうと最後まで再生されないようです。
あるいはAuSoundPlaySynchronousFromFileを使いましょう。
こちらは再生が終わるまでブロックされます。)
AuServer *server;//AuOpenServerで接続したサーバーを指定します。
char *filename;//再生させたいファイル名を指定します。
//nasに付属のdoc/library.psに依ると.snd,.au,.voc,.wav,.aiffに
//対応してるそうです。(実際にはサーバー依存?)
AuDeviceID destination;//再生させたいdeviceを指定します。
                       //取り敢えずAuNoneを指定するとサーバーがよきにはから
                       //ってくれます。
                       //deviceの探し方は次に基本的な使い方で説明します。
                       
AuFixedPoint volume;//ボリュームを指定します。AuFixedPointは上で解説済み
void   (*callback) (AuServer *,AuEventHandlerRec*,AuEvent *,AuPointer);
//callbackを指定します。特に何もする必要がなければNULLを指定します。
AuPointer callback_data;//callbackに渡されるデータを指定します。
                        //必要ないならばNULLを指定します。
AuFlowID *flow; /* RETURN */以下の四つは無関心ならばNULLを書きます。
int *volume_mult_elem; /* RETURN */
int *monitor_element; /* RETURN */
AuStatus *status; /* RETURN */

NASに含まれているclients/audio/examples/playFile.cも参照してください。







*基本的な使い方
ここではまず、基本的なデータ型について説明した後、
elementを使っていろいろなflowを作成して、データを再生してみます。
又、イベントの扱いについても触れます。
see bucket.cc,eventHandling.cc

まずは基本となるデータ型について説明します。
AuServer serverを示すものです。
AuFlowID flow objectを示すものです。
AuDeviceAttributes deviceの性質を表すものです。(例えばモノラルだとかステレオだとか)
AuDeviceID           Deviceを表すものです。
AuBucketID           bucketを表すものです。
AuBucketAttributes   bucketの性質を表すものです。
Sound                audio dataの性質を表すものです。(例えばformatやsampling rateやモノラルかステレオかなど)
AuElement            elementを示すものです。(elementとは上で説明しました。)
AuInputTrack         trackを表すものです。(これはelementをつなげるのに使います。例えばステレオの片方のみを取りだしたりに使います。)
AuEvent              serverから通知されるイベントです。
AuBool               boolean値を表すもので、AuTrue,AuFalseの値を取ります。
AuEventHandlerRec *  event handler等を示します
AuElementAction      actionを定義するために使う物です。(これはadvancedな使い方で説明します。)

note:Import,Export importは(dataを)出力する(音を再生)ことを表し、exportは入力をする(録音)ことを表します。


定数
AuDataFormats audio dataのformatにはいろいろ有りますが、これらは次の定数で
表されます。
AuFormatULAW8                   u-law
AuFormatLinearUnsigned8         linear unsigned 8bit
AuFormatLinearSigned8           linear singed 8bit
AuFormatLinearSigned16MSB       linear singed 16bit msb first
AuFormatLinearUnsigned16MSB     linear unsigned 16bit msb first
AuFormatSignedLinear16LSB       linear singed 16bit lsb first
AuFormatLinearUnsigned16LSB     linear unsigned 16bit lsb first

AuFileFormat fileのformat
SoundFileFormatSnd              .snd
SoundFileFormatVoc              .voc
SoundFileFormatWave             .wav
SoundFileFormatAiff             .aiff
SoundFileFormatSvx              .svx

State componentの状態を示します。
AuStateStop    停止状態
AuStateStart   再生開始
AuStatePause   停止状態
AuStateAny     上の全て
StopとPauseの違いはstopはこれ以上データがもう無い状態で
pauseは一時的に止まっているものでまたデータの移動が再開する事
(事がありえる)状態です。

element type:elementの種類は次で表されます。
だいたい名前から想像が付くでしょう。(使う物は便宜説明します。)
AuElementTypeAddConstant
AuElementTypeBundle
AuElementTypeExportBucket
AuElementTypeExportClient
AuElementTypeExportDevice
AuElementTypeExportMonitor
AuElementTypeImportClient
AuElementTypeImportDevice
AuElementTypeImportBucket
AuElementTypeImportWaveForm
AuElementTypeMultiplyConstant
AuElementTypeSum

wave virtual deviceが作り出す波の形は次の定数で表されます。
AuWaveFormSquare   方形波
AuWaveFormSine     サイン波
AuWaveFormSaw      三角波
AuWaveFormConstant 定数波

AuEventType eventの種類を表します。現在次のタイプがあります。
AuEventTypeElementNotify        elementのstateが変化したときに発生するイベント
AuEventTypeMonitorNotify        monitor dataを送くるイベント(Monitor Deviceが生成する?)
AuEventTypeGrabNotify           

AuStatus serverの状態を示すものです。Status Codes
ま、次の様なものがあるというだけでいいでしょう。
AuSuccess                       /* no problems */
AuBadRequest                    /* bad request code */
AuBadValue                      /* int value out of range */
AuBadDevice                     /* bad physical device ID */
AuBadBucket                     /* bad bucket ID */
AuBadFlow                       /* bad flow ID */
AuBadElement                    /* bad portal ID */
AuBadMatch                      /* parameter mismatch */
AuBadAccess                     /* permission denied */
AuBadAlloc                      /* insufficient resources */
AuBadConnection                 /* problem with network */
AuBadIDChoice                   /* bad ID provided for Create */
AuBadName                       /* named object doesn't exist */
AuBadLength                     /* bad request length */
AuBadImplementation             /* bad server, no cookie */

AuLastError                     AuBadImplementation
AuFirstExtensionError           128
AuLastExtensionError            255


Looking for Device:再生するdeviceを探します。
//look for an output device
//auServer//AuOpenServerの帰り値です。
const int NUM_TRACS=1;//1:monoral 2:stereo
for (int i=0;i<AuServerNumDevices(auServer);i++)
  {
    if ((AuDeviceKind(AuServerDevice(auServer,i))==
         AuComponentKindPhysicalOutput) &&
        AuDeviceNumTracks(AuServerDevice(auServer,i))==NUM_TRACKS)
      {
        auDevice=AuDeviceIdentifier(AuServerDevice(auServer,i));
        break;
      }
  }

詳しい説明
int AuServerNumDevices (AuServer* audio)
これでサーバーにあるdeviceの数を知ることができます。macro
AuDeviceAttributes* AuServerDevice (AuServer* audio,int num)
これでサーバーにあるnum番目のdeviceのAuDeviceAttributesを得ます。
AuDeviceKind AuDeiceKind (AuDeviceAttributes* device)
deviceで表されるdeviceの種類を知ります。macro
AuDeviceKind 種類は以下の定数で表されます。
AuComponentKindPhysicalInput 録音をするもの mic等
AuComponentKindPhysicalOutput 再生をするもの speaker等
int AuDeviceNumTracks(AuDeviceAttributes* device)
deviceのトラック数を得ます。つまり＝1ならばモノラルで＝2ならばステレオという事です。macro
AuDeviceID AuDeviceIdentifier (AuDeviceAttributes* device)
deviceで示されるdeviceのAuDeviceIDを得ます。macro





Creating flow and play data
int volume=100;//volumeを指定します。
int sampleRate=22500;//sampling rateを指定します。
int NOAUDIO_FRAG_SIZE=BUFFER_SIZE;//bufferのサイズを指定します。
AuElement elements[3];
AuMakeElementImportClient(&elements[0],sampleRate,AuFormatLinearUnsigned8,
                          NUM_TRACKS,
                          AuTrue,
                          AuUnlimitedSamples,
                          NOAUDIO_FRAG_SIZE,
                          0, NULL);
AuMakeElementMultiplyConstant(element[1],0,
                              AuFixedPointFromFraction (volume,100));
AuMakeElementExportDevice(&elements[2],1,auDevice,sampleRate,
                          AuUnlimitedSamples,0,NULL);

//////////////////set flow
AuFlowID auFlow;
auFlow=AuCreateFlow(auServer,NULL);
if (auFlow!=AuNone)
  {
    cerr << "Couldn't create flow." << endl;
    exit (-1);
  }
AuSetElements(auServer,auFlow,AuTrue,2,elements,NULL);

///////////////start flow
AuStartFlow(auServer, auFlow, NULL);

////////////////write data
char data[NUM_OF_DATA];//ここにデータがあるとします。
                       //(事前にファイルから読み込むなりしておく。)
AuWriteElement (auServer,auFlow,0,NUM_OF_DATA,(AuPointer)data,
                AuFalse,NULL);

詳しい説明
下図の様なflowを作成しています。
                                        AuFixedPointFromFraction (volume,100)
                                       /
write data--->client----->multiply  *(volume/100)-->export device(speaker)
              element[0]  element[1]               element[2]


AuMakeElementImportClient
(AuElement *element /* RETURN */,
 unsigned short sample_rate,
 unsigned char format,
 unsigned char num_tracks,
 unsigned char discard,
 AuUint32 max_samples,
 AuUint32 low_water_mark,
 int num_actions,
 AuElementAction *actions)
importclient elementを初期化します。
AuElement *element           これによって得られるelementが返ります。
unsigned short sample_rate   sampling rateを指定します。
unsigned char format         dataのformatを指定します。
unsigned char num_tracks     track numberを指定します。(1:monoral,2:stereo)
unsigned char discard        AuTrue又はAuFalseを指定します。初期化したあとPause状態にするか否かです。通常はAuTrueを指定します。
AuUint32 max_samples         一度に受け付けるsampling rateを指定します。
(実は何を指定しているのは良く分かりません。
知っている方がいたら教えてください。)
AuUnlimitedSamplesを指定しておけば良いようです。
AuUint32 low_water_mark     low water markを指定します。bufferのデータがこれ以下になるとAuElementNotifyKindLowWaterが送られます。
int num_actions             次のactionの数を指定します。指定しないならば0を指定します。
AuElementAction *actions    elementに設定したいactionを指定します。特に必要なければNULLを指定します。

AuMakeElementMultiplyConstant
(AuElement *element/* RETURN */,
unsigned short input,
AuFixedPoint constant)
AuElementTypeMultiplyConstantを初期化します。
inputからの入力をconstant倍したものを出力します。
AuElement *element         このエレメントを返します。
unsigned short input       入力先のelement番号を指定します。
AuFixedPoint constant      定数倍する値を指定します。

AuMakeElementExportDevice
(AuElement *element/* RETURN */,
 unsigned short input,
 AuDeviceID device,
 unsigned short sample_rate,
 AuUint32 num_samples,
 int num_actions,
 AuElementAction *actions)
出力device(通常はスピーカーでしょう。)を初期化します。
AuElement *element           このelementを返します。
unsigned short input         入力先のelement番号を指定します。
AuDeviceID device            出力先のdevice IDを指定します。
unsigned short sample_rate   sampling rateを指定します。
AuUint32 num_samples         一度にdeviceに送られるsample rateを指定します。
(実は何を指定しているのは良く分かりません。
知っている方がいたら教えてください。)
通常はAuUnlimitedSamplesを指定しておけば問題無い様です。
int num_actions             次のactionの数を指定します。指定しないならば0を指定します。
AuElementAction *actions    elementに設定したいactionを指定します。特に必要なければNULLを指定します。


AuFlowID AuCreateFlow(AuServer *server,AuStatus *status/* RETURN */)
flowを作成します。
AuServer *server    serverを指定します。何かエラーがあればAuNoneが返ります。
AuStatus *status    flowの状態が返ります。

void  AuSetElements
(AuServer *server,
 AuFlowID flow,
 AuBool clocked,
 int num_elements,
 AuElement *elements,
 AuStatus *status/* RETURN */)
flowで示されるflowにelementを設定します。
AuServer *server       serverを指定します。
AuFlowID flow          設定するflowを指定します。
AuBool clocked         (clockedという事はどういう事か良く分かりません。知っている方がいらしたら教えてください。)
clockedするかどうか指定します。AuTrueを指定しておけば良いようです。
int num_elements       elementの数を指定します。
AuElement *elements    設定するelementを指定します。
AuStatus *status       non-NULLを指定するとサーバーのstatusが返ります。
                       特に必要がなければNULLを指定しておけば良いでしょう。

void AuStartFlow(AuServer *server,AuFlowID flow,AuStatus *status/* RETURN */)
flowをスタートさせます。(そのままやな。何の説明になってないなぁ。)ここでスタートする必要は無いかな。
AuServer *server      serverを指定します。
AuFlowID flow         flowを指定します。
AuStatus *status      non-NULLを指定するとサーバーのstatusが返ります。
                      特に必要がなければNULLを指定しておけば良いでしょう。

void  AuWriteElement
(AuServer *server,
 AuFlowID flow,
 int element,
 AuUint32 num_bytes,
 AuPointer data,
 AuBool end_of_data,
 AuStatus *status/* RETURN */)
import elementにデータを書き込みます。
AuServer *server     サーバーを指定します。
AuFlowID flow        flowを指定します。
int element          データを書き込むelementの番号を指定します。
AuUint32 num_bytes   書き込むデータのバイト数を指定します。
AuPointer data       書き込むデータ
AuBool end_of_data   これが最後のデータか?
AuStatus *status     帰り値









Playing the Data:dataの再生
char pcmData[size]にデータが入っているものとします。
Sound sound=SoundCreate (0,AuFormatLinearUnsigned8,NUM_TRACKS,sampleRate,
                         size,NULL);
AuBucketID bucket=AuSoundCreateBucketFromData (auServer,sound,
                                               (AuPointer) pcmData,
                                               0,NULL,NULL);
AuSoundPlayFromBucket(auServer,bucket,auDevice,AuFixedPointFromSum(1,1),
                      NULL,NULL,1,NULL,NULL,NULL,NULL);
AuFlush (auServer);

詳しい説明。
Sound  SoundCreate
(int file_format,
 int data_format,
 int num_tracks,
 int sample_rate,
 int num_samples,
 char *comment)
bucketの属性を指定するためのSoundを作成します。
int file_format    fileのformatを指定します。(AuSoundCreateBucketFromFileを使う時に使用されます?)
int data_format    dataのformatを指定します。(AuSoundCreateBucketFromDataを使う時に使用されます?)
int num_tracks     track数を指定します。(=1:mono =2:stereo)(AuSoundCreateBucketFromDataを使う時に使用されます?)
int sample_rate    sampling rateを指定します。(AuSoundCreateBucketFromDataを使う時に使用されます?)
int num_samples    dataのバイト数を指定します。(AuSoundCreateBucketFromDataを使う時に使用されます?)
char *comment      コメント?ま、NULLを指定すればいいでしょう。
AuBucketID   AuSoundCreateBucketFromData
(AuServer *server,
 Sound sound,
 AuPointer data,
 AuUint32 access,
 AuBucketAttributes **attributes/* RETURN */,
 AuStatus *status/* RETURN */)
bucket elementを作成します。
AuServer *server         serverを指定します。
Sound sound              dataの属性を指定します。
AuPointer data           dataを指定します。
AuUint32 access          (良く分かりません。知ってられる方がいたら教えてください。)取り敢えず0を入れておけば問題無い様です。
AuBucketAttributes **attributes
                         bucketのattributesが返ります。必要無ければNULLを入れておきましょう。
AuStatus *status         サーバーのstatusが返ります。必要無ければNULLを入れておきましょう。
fileからバケットを作るなら次を使います。
AuBucketID  AuSoundCreateBucketFromFile
(AuServer *server,
 char *filename,
 AuUint32 access,
 AuBucketAttributes **attributes/* RETURN */,
 AuStatus *status/* RETURN */)

AuEventHandlerRec  *AuSoundPlayFromBucket
(AuServer *server,
 AuBucketID source,
 AuDeviceID destination,
 AuFixedPoint volume,
 void (*callback)  (AuServer  *,AuEventHandlerRec  *, AuEvent *, AuPointer),
 AuPointer callback_data,
 int loop_count,
 AuFlowID *flow/* RETURN */,
 int *volume_mult_elem/* RETURN */,
 int *monitor_element/* RETURN */,
 AuStatus *status/* RETURN */)

AuServer *server              serverを指定します。
AuBucketID source             再生元のbucketを指定します。
AuDeviceID destination        音を再生するdeviceを指定します。
AuFixedPoint volume           volumeを指定します。
void (*callback)  (AuServer  *,AuEventHandlerRec  *, AuEvent *, AuPointer)
                              event handlingを行う為のhandlerを登録します。
                              必要無ければNULLを指定しましょう。
AuPointer callback_data       上のcallbackに渡されるデータを指定します。
int loop_count                ループ回数を指定します。
AuFlowID *flow                flowが返ります。(これ以下のものは必要無ければNULLを指定しましょう。)
int *volume_mult_elem         volumをAuElementTypeMultiplyConstantが返ります。
int *monitor_element          monitor elementが返ります。
AuStatus *status              サーバーのstatusが返ります。










Playing the Data:dataの再生その2
///////////////////////////////////////////////////look for an output device
const int NUM_TRACKS=2;//1:monoral 2:stereo
AuDeviceID auDevice;
for (int i=0;i<AuServerNumDevices(auServer);i++)
  {
    if ((AuDeviceKind(AuServerDevice(auServer,i))==
         AuComponentKindPhysicalOutput) &&
        AuDeviceNumTracks(AuServerDevice(auServer,i))==NUM_TRACKS)
      {
        auDevice=AuDeviceIdentifier(AuServerDevice(auServer,i));
        break;
      }
  }
/////////////////////////////////////////////////////////constructing flow
AuBucketID bucket=AuSoundCreateBucketFromFile (auServer,fileName,
                                               0,NULL,NULL);
AuBucketAttributes* bucketAttributes=AuGetBucketAttributes (auServer,bucket,NULL);
AuElement element[4];
AuInputTrack track[2];
AuMakeElementImportBucket(&element[0],
                          AuBucketSampleRate (bucketAttributes),
                          bucket,
                          AuBucketNumSamples (bucketAttributes),
                          0,0,NULL);
AuMakeInputTrack(&track[0],0,0);
AuMakeElementMultiplyConstant (&element[1],0,
                               AuFixedPointFromFraction (-1,1));
AuMakeInputTrack (&track[1],1,0);
AuMakeElementBundle(&element[2],2,track);
AuElementAction action[2];
AuMakeElementExportDevice(&element[3],2,auDevice,
                          AuBucketSampleRate (bucketAttributes),
                          AuUnlimitedSamples,0,NULL);
AuFreeBucketAttributes (auServer,1,bucketAttributes);
///////////////////////////////////////////////////////create flow
AuFlowID auFlow=AuCreateFlow(auServer,NULL);
if (auFlow==AuNone)
  {
    cerr << "Couldn't create flow." << endl;
    exit (-1);
  }
///////////////////////////////////////////////////////////////////set flow
AuSetElements(auServer,auFlow,AuTrue,4,element,NULL);
///////////////////////////////////////////////////////////////play the data
AuStartFlow(auServer, auFlow, NULL);
AuFlush (auServer);

詳しい説明
note:この例は再生がステレオでなければうまくいきません。
monoralしか再生できなくてもサーバーがstereo dataを合成してmonoralで再生して
くれるような場合は音が出ませんので注意。(正確には無音データが再生されている
のですが。x+(-x)=0:無音)
以下のようなflowを作っています。
                  track[0]
              +-------------->---+
              |                  |
bucket(mono data)             bundler:element[2]=>=Device(stereo speaker)
element[0]    |                  |                 element[3]
              +---Multi -1--->---+
                  element[1]  track[1]


AuBucketAttributes* bucketAttributes=AuGetBucketAttributes (auServer,bucket,NULL);
AuBucketAttributes  *AuGetBucketAttributes
(AuServer *server,
 AuBucketID bucket,
 AuStatus *status/* RETURN */)
bucketの属性を得ます。このbucketAttributesから次の様なマクロを使って情報を知ることができます。
(ここに挙げたもの以外にも有りますが詳しくはman 3 AuBucketAttributesを参照のこと)
AuBucketAttributes ba;
AuBucketIdentifier(ba)
AuBucketFormat(ba)
AuBucketNumTracks(ba)
AuBucketSampleRate(ba)
AuBucketNumSamples(ba)

AuMakeElementImportBucket
(AuElement *element/* RETURN */,
 unsigned short sample_rate,
 AuBucketID bucket,
 AuUint32 num_samples,
 AuInt32 offset,
 int num_actions,
 AuElementAction *actions)
再生するためのbucket elementを初期化します。
AuInt32 offset             dataを再生するときのオフセットを指定します。ま、必要がなければ0でしょう。
(例えばAuSoundCreateBucketFromDataで作成したbucketのheaderの部分を飛ばしたり
するのに使います。これはAuSoundCreateBucketFromFileから作ったbucketなら0で
良いです。)
int num_actions            actionの数を指定します。特に指定しないのなら0を指定します。
AuElementAction *actions   指定したいactionを書きます。不要ならNULLを書きます。


AuBucketAttributes* bucketAttributes=AuGetBucketAttributes (auServer,bucket,NULL);
AuMakeInputTrack(&track[0],0,0);
AuMakeInputTrack
(AuInputTrack *track/* RETURN */,
unsigned short element_num,
unsigned char track)
AuInputTrack *track           作られたtrackが返ります。
unsigned short element_num    trackを取り出したいelementの番号を指定します
unsigned char track           取り出したいtrack番号を指定します。
                              この場合はmonoral dataなので0番しか有りません。
                              stereo dataの場合は0番と1番があります。
                              (どちらかが右でもう一方が左のデータです。
                              どっちがどちらなのでしょう?)

AuMakeElementMultiplyConstant (&element[1],0,
                               AuFixedPointFromFraction (-1,1));
これで逆位相にします。

AuMakeElementBundle(&element[2],2,track);
AuMakeElementBundle
(AuElement *element/* RETURN */,
 unsigned short num_inputs,
 AuInputTrack *inputs)
一つ以上のtrackを併せて一つのデータにします。
二つのtrackを併せるという事は二つのmonoral dataからstereo dataを作り出すという事です。
AuElement *element            出来たelementを返します。    
unsigned short num_inputs     trackの数を指定します。
AuInputTrack *inputs          trackを指定します。


AuFreeBucketAttributes (auServer,1,bucketAttributes);
void      AuFreeBucketAttributes
(AuServer *server,
 int nattributes,
 AuBucketAttributes *attributes)
これで不要になったAuBucketAttributesを解放します。
int nattributes                  解放するattributesの数を指定します。    
AuBucketAttributes *attributes   解放するattributesを指定します。

AuStartFlow(auServer, auFlow, NULL);
これで再生を開始します。AuSetElements(auServer,auFlow,AuTrue,4,element,NULL);
でflowを作ったときは状態はpauseです。(AuTrue)















event handling
再生が終了するまで待ちます。
/////////////////////////////////////////////////////wait for playing
for (;;)
  {
    AuEvent event;
    AuNextEvent (auServer,AuTrue,&event);
    if (event.type==AuEventTypeElementNotify)
      {
        AuElementNotifyEvent* notifyEvent=(AuElementNotifyEvent *) &event;
        if (notifyEvent->cur_state==AuStateStop)
          break;
      }
  }
詳しい説明
AuNextEvent (auServer,AuTrue,&event);
void AuNextEvent(AuServer *server,AuBool dequeue,AuEvent *event/* RETURN */)
これでイベントを取得します。イベントが無ければブロックされます。
AuBool dequeue       event queueからイベントを取り除くか否かを指定します。
                     通常はAuTrueでしょう。

if (notifyEvent->cur_state==AuStateStop)
  break;
これで再生が終了したらfor loopを抜けます。











event handlingその2
static AuBool eventHandler (AuServer* auServer,
                            AuEvent* event,
                            AuEventHandlerRec* handler)
{
  AuBool *isDone=(AuBool *) handler->data;
  AuElementNotifyEvent* notifyEvent=(AuElementNotifyEvent *) event;
  
  if (notifyEvent->type==AuEventTypeElementNotify &&
      notifyEvent->kind==AuElementNotifyKindState &&
      notifyEvent->cur_state==AuStateStop)
    *isDone=AuTrue;
  
  return AuTrue;
};

static void doSomething ()
{
  cout << "doing something." << endl;
};

----------------------------------------------------------------main内
AuBool isDone=AuFalse;
AuEventHandlerRec* handler=
  AuRegisterEventHandler (auServer,AuEventHandlerIDMask,0,auFlow,
                          eventHandler,(AuPointer) &isDone);
if (!handler)
  {
    cerr << "can not register event handler" << endl;
    exit (-1);
  }

while (!isDone)
  {
    AuEvent event;
    //const int mode=AuEventsQueuedAlready;
    //const int mode=AuEventsQueuedAfterReading;
    const int mode=AuEventsQueuedAfterFlush;
    if (AuScanForTypedEvent (auServer,mode,AuTrue,AuEventTypeElementNotify,
                             &event)==AuTrue)
      {
        AuDispatchEvent (auServer,&event);
      }
    else
      {
        doSomething ();
      }
  }

詳しい説明
AuEventHandlerRec* handler=
AuRegisterEventHandler (auServer,AuEventHandlerIDMask,0,auFlow,
                        eventHandler,(AuPointer) &isDone);

AuEventHandlerRec *AuRegisterEventHandler
(AuServer *server,
 AuMask value_mask,
 int type,
 AuID id,
 AuBool (*callback)(AuServer *,AuEvent *,AuEventHandlerRec *),
 AuPointer data)
event handlerを登録します。
int type            処理するイベントのタイプを指定します。
AuID id             どこで起きたeventを処理するのか指定します。
AuBool (*callback)(AuServer *,AuEvent *,AuEventHandlerRec *)
                    登録するevent handlerを指定します。
AuPointer data      event handlerに渡すデータを指定します。
AuEventHandlerRec* handler;
handler->dataで取り出します。
何かエラーが起きたときはNULLが返ります(?)
AuScanForTypedEvent (auServer,mode,AuTrue,AuEventTypeElementNotify,&event)
AuBool AuScanForTypedEvent
(AuServer *server,
 int mode,
 AuBool dequeue,
 int type,
 AuEvent *event/* RETURN */)
ブロックされずにイベントを取り出すのに使います。
ブロックされずにイベントを取り出すにはもう一つAuScanEvents ()というのもあります。
int mode       AuEventsQueuedAlready,
               AuEventsQueuedAfterReading,
               AuEventsQueuedAfterFlush.
               のいずれかを指定します。
int type       取り出したいイベントのタイプを指定します。










mixing
AuElementTypeSumを用いるとmixingが行えます。
//element[0]とelement[1]は何か再生させたいデータが来ているものとします。
//必要によってエレメントの番号を指定する所はずらす必要があるでしょう。
element[5];
AuMakeElementMultiplyConstant (&element[2],0,AuFixedPointFromFraction (1,2));
AuMakeElementMultiplyConstant (&element[3],1,AuFixedPointFromFraction (1,2));
unsigned short inputs[2];
inputs[0]=2;
inputs[1]=3;
AuMakeElementSum (&element[4],2,inputs);
詳しい説明
以下のようなflowを作成します。
因に入力の一つをmicにしてもう一つをCDにし、出力をスピーカーにするとカラオケですね。
element[0]-->--multi 1/2:element[2] inputs[0]=2
                                  \____    
                                   ____ SUM:element[4]-> mixed data
                                  /
element[1]-->--multi 1/2:element[3] inputs[1]=3

AuMakeElementSum (&element[4],2,inputs);
AuMakeElementSum
(AuElement *element/* RETURN */,
 unsigned short num_inputs,
 unsigned short *inputs)
unsigned short num_inputs   足し合わせるエレメントの数を指定します。
unsigned short *inputs      足し合わせるエレメントの番号を指定します。










clean up:後始末。
AuUnregisterEventHandler (auServer,handler);
AuFreeBucketAttributes (auServer,1,bucketAttributes);
AuDestroyBucket (auServer,bucket,NULL);
AuDestroyFlow (auServer,auFlow,NULL);
AuCloseServer (auServer);
確保したものを開放します。













*advancedな使い方
ここではアクションを用いたより低levelな制御について説明します。
see action.cc

actionの使い方
AuMakeElementState ()
AuMakeChangeStateAction ()
AuMakeChangeStateAction ()
AuMakeNoopAction ()
AuMakeSendNotifyAction ()


actionとはcomponentがある状態になったときにある動作を引き起こさせる事を言います。
それらはAuElementAction構造体で記述されます。

以下の定数が使われます。
Action
AuElementActionChangeState      状態を変化させます。
AuElementActionSendNotify       notify eventを通知します。
AuElementActionNoop             何もしない。

trigger reason
AuReasonUser                    
AuReasonUnderrun
AuReasonOverrun
AuReasonEOF
AuReasonWatermark
AuReasonHardware
AuReasonAny

なお、defaultのactionは次の様になっています。(nasのdoc/actionから引用)
>Component       Action          Trigger Prev    Reason  Flow    Element State
>--------------- --------------- ------- ------- ------- ------- ------- -----
>
>ImportClient    SendNotify      Pause   Any     Any
>     "          SendNotify      Stop    Any     Any
>     "          ChangeState     Pause   Any     Any     Own     All     Pause
>     "          ChangeState     Start   Pause   Any     Own     All     Start
>     "          ChangeState     Stop    Any     Any     Own     All     Stop
>
>ImportDevice    (None)
>
>ImportBucket    SendNotify      Pause   Any     Any
>     "          SendNotify      Stop    Any     Any
>     "          ChangeState     Stop    Any     Any     Own     All     Stop
>
>ImportWaveForm  SendNotify      Pause   Any     Any
>     "          SendNotify      Stop    Any     Any
>     "          ChangeState     Stop    Any     Any     Own     All     Stop
>
>ExportClient    SendNotify      Pause   Any     Any
>     "          SendNotify      Stop    Any     Any
>     "          ChangeState     Pause   Any     Any     Own     All     Pause
>     "          ChangeState     Start   Pause   Any     Own     All     Start
>     "          ChangeState     Stop    Any     Any     Own     All     Stop
>
>ExportDevice    (None)
>
>ExportBucket    SendNotify      Pause   Any     Any
>     "          SendNotify      Stop    Any     Any
>     "          ChangeState     Stop    Any     Any     Own     All     Stop
>
>ExportMonitor   (None)

Elementの項目はelement番号を指定しますが、AuElementAllを指定する事も出来ます。

AuElementActionを設定するには次を使います。
AuMakeChangeStateAction
AuMakeSendNotifyAction
AuMakeNoopAction

又、elementの状態を変化させるには(再生を止めたり等)
AuElemnetState構造体を
AuMakeElementStateを使って初期化して、
AuSetElementStates
を用います。

また、elementのパラメーターを動的に変化させるにはAuSetElementParametersを使う様なのですが、使い方が良く分かりません。
またactionを動的に変化させる方法は分かりません。
知っておられる方がいらしたら教えてください。



二つのデータを交互に切目無く再生する。
///////////////////////////////////////////////////////////set action
AuElementAction action[4];
////action for bucket0 element[0]
AuMakeChangeStateAction (&action[0],AuStateStop,AuStateStart,AuReasonEOF,
                         flow,
                         1,//this 1 is for element[1](i.e bucket0)
                         AuStateStart);
AuMakeSendNotifyAction (&action[1],AuStateStop,AuStateStart,AuReasonEOF);
////action for bucket1 element[1]
AuMakeChangeStateAction (&action[2],AuStateStop,AuStateStart,AuReasonEOF,
                         flow,
                         0,//this 0 is for element[0](i.e. bucket0)
                         AuStateStart);
AuMakeSendNotifyAction (&action[3],AuStateStop,AuStateStart,AuReasonEOF);
//////////////////////////////////////////////////create elements & set flow
AuElement element[4];
AuInputTrack track[2];
AuBucketID bucket0=AuSoundCreateBucketFromFile (auServer,firstFileName,
                                                0,NULL,NULL);
AuBucketAttributes* bucketAttributes0=
  AuGetBucketAttributes (auServer,bucket0,NULL);
AuMakeElementImportBucket(&element[0],
                          AuBucketSampleRate (bucketAttributes0),
                          bucket0,
                          AuBucketNumSamples (bucketAttributes0),
                          0,2,&action[0]);
AuMakeInputTrack (&track[0],0,0);
 AuBucketID bucket1=AuSoundCreateBucketFromFile (auServer,secondFileName,
                                                0,NULL,NULL);
AuBucketAttributes* bucketAttributes1=
  AuGetBucketAttributes (auServer,bucket1,NULL);
AuMakeElementImportBucket(&element[1],
                          AuBucketSampleRate (bucketAttributes1),
                          bucket1,
                          AuBucketNumSamples (bucketAttributes1),
                          0,2,&action[2]);
AuMakeInputTrack (&track[1],1,0);
 AuMakeElementBundle (&element[2],2,track);
 AuMakeElementExportDevice(&element[3],2,auDevice,
                          AuBucketSampleRate (bucketAttributes0),
                          AuUnlimitedSamples,0,NULL);
AuSetElements (auServer,flow,AuTrue,4,element,NULL);
////////////////////////////////////////////////////////////trash
AuFreeBucketAttributes (auServer,1,bucketAttributes0);
AuFreeBucketAttributes (auServer,1,bucketAttributes1);
AuDestroyBucket (auServer,bucket0,NULL);
AuDestroyBucket (auServer,bucket1,NULL);
////////////////////////////////////////////////////start playing
AuElementState stat[2];
AuMakeElementState (&stat[0],flow,0,AuStateStart);
AuMakeElementState (&stat[1],flow,3,AuStateStart);
AuSetElementStates (auServer,2,stat,NULL);
AuFlush (auServer);

詳しい説明
以下のようなflowを作っています。
通常はbundleを使わずにsumを使い、必要なだけbucketをつなげるのでしょう。
                  track[0]
bucket0(mono)-------------
element[0]                \
                           bundle========Device(stereo)
                          / element[2]   element[3]
bucket1(mono)-------------
element[1]       track[1]

AuMakeChangeStateAction
(AuElementAction action/* RETURN */,
 unsigned char trigger_state,
 unsigned char trigger_prev_state,
 unsigned char trigger_reason,
 AuFlowID flow,
 unsigned char element_num,
 unsigned char new_state)
actionにChangeStateActionを設定します。
trigger_state,trigger_prev_state,trigger_reason,
この三つで示される状態になった時に
flow,element_numで示されるelementをnew_stateにします。
element_numはAuElementAllを指定する事も出来ます。
この例では二つのbucketを交互に切目無く再生する様に設定しています。
SendNotifyActionやNoopActionを設定するにはそれぞれ
AuMakeSendNotifyAction
(AuElementAction action/* RETURN */,
 unsigned char trigger_state,
 unsigned char trigger_prev_state,
 unsigned char trigger_reason)

AuMakeNoopAction
(AuElementAction action/* RETURN */,
 unsigned char trigger_state,
 unsigned char trigger_prev_state,
 unsigned char trigger_reason)
を用います。

AuMakeElementState
(AuElementState *state/* RETURN */,
 AuFlowID flow,
 unsigned char element_num,
 unsigned char state)
これでAuSetElementStatesで使うstateの初期化をします。

void  AuSetElementStates
(AuServer *server,
 int num_states,
 AuElementStates *states,
 AuStatus *status/* RETURN */)
これでelementのstateを指定した状態にします。
この例では片方のbucketの再生を開始しています。


*録音等について
これは使ったことがないので関連のありそうなキーワードを挙げるにとどめます。
これらのmanを見れば何とかなると思います。
(あるいはだれか心優しい方がここを書いてください。)
AuMakeElementImportDevice ()
AuMakeElementExportBucket ()
AuMakeElementExportClient ()
AuReadElement ()
AuSoundCreateDataFromBucket ()
AuSoundCreateFileFromBucket ()
AuSoundRecord ()
AuSoundRecordToBucket ()
AuSoundRecordToData ()
AuSoundRecordToFile ()
AuSoundRecordToFileN ()
SoundAbbrevToFileFormat ()
SoundCloseFile ()
SoundFlushFile ()
SoundOpenFileForReading ()
SoundOpenFileForWriting ()
SoundRewindFile ()
SoundSeekFile ()
SoundTellFile ()
SoundWriteFile ()


*examples
elementary.cc
bucket.cc
eventHandling.cc
action.cc



*Xtとの連携
必要な方はXtutil.hを見れば十分でしょう。(投げやり)
以下Xtutil.hの引用。
/*
 * AuXtHandleAudioEvents - this routine extracts the AuServer from the
 * Xt callback data and then calls AuHandleEvents.
 */
extern void AuXtHandleAudioEvents (
#if NeedFunctionPrototypes
        XtPointer,      /* caller_arg */
        int *,          /* ptr_to_source */
        XtInputId *     /* opaque_inputid */
#endif
);


/*
 * AuXtAppAddAudioHandler - this routine adds AuXtHandleAudioEvents as an
 * Xt input handler to deal with audio events.  This allows the audio service
 * to be used from Xt programs without disturbing their main loop.
 */
extern XtInputId AuXtAppAddAudioHandler (
#if NeedFunctionPrototypes
        XtAppContext,   /* app_context */
        AuServer *      /* server */
#endif
);
extern void
AuXtAppRemoveAudioHandler(
#if NeedFunctionPrototypes
       AuServer *,              /* server */
       XtInputId
#endif
);



*その他触れておくべき事


*NASの入手及びinstallの仕方
ftp:://ftp.x.org/contrib/audio/nas/
にあります。近くでミラーしている所から入手しましょう。
READMEに従ってinstallしましょう。


*参考文献
NASのdistributionに付属のdocument(特にlibrary.ps,xcon94paper.ps,actions,とman)


*Contact
Yamahata Isaku(ISA-9)
e-mail:
CQG00274@niftyserve.or.jp
yamahata@kusm.kyoto-u.ac.jp