PCM digital Plugin のドキュメンテーション (http://www.alsa-project.org/alsa-doc/alsa-lib/pcm_plugins.html)を、自分が参照するために勝手に翻訳。ＰＣＭとかの基本が分かってないから訳せないところがたくさんあるし、いい加減なところがたくさんあるから、それで痛い目に遭うかもしれないけどしょうがないw。
コードの部分は形が崩れてるところがあります。あと、リンクは無視してください。ここの中で base URL は指定できなかった（面倒臭くて書き直さなかった）ものですから…。
---- believe or not 以下勝手翻訳 ----
ＰＣＭプラグインはＰＣＭデバイスの機能とフィーチャーを拡張します。プラグインはさまざまなサンプル変換、チャンネル間のサンプルコピーなどを take care about します。
"slave" プラグインは文字列で直接特定されます。つまり 定義複合体ノードの中で enter されます。static rate やチャンネル数など一部の restrictions も明示されます。
pcm_slave.NAME {
pcm STR # PCM 名
# or
pcm { } # PCM 定義
format STR # フォーマット or 文字列 "unchanged"
channels INT # チャンネル数 or "unchanged"
rate INT # サンプリングレート(Hz) or "unchanged"
period_time INT # Period time in us or "unchanged"
buffer_time INT # Buffer time in us or "unchanged"
}
例 :
pcm_slave.slave_rate44100Hz {
pcm "hw:0,0"
rate 44100
}
pcm.rate44100Hz {
type plug
slave slave_rate44100Hz
}
１つのコンパウンドで表現すると :
pcm.rate44100Hz {
type plug
slave {
pcm "hw:0,0"
rate 44100
}
}
このプラグインは ALSA カーネルドライバと直接情報をやりとりします（変換せずそのまま :
a raw communication without any conversions）。mmap アクセスのエミュレーションも選択的に有効にすることができますが、
expect worse latency in the case.
ノンブロック・オプションは、デバイスがノン・ブロッキングで開かれるかどうかを指定します。ただしこのオプションでは、読み書きアクセスに関するブロックの挙動を変更することはできません。古い ALSA（ALSA stuff） との互換性を保つには、このオプションを OFFしてください。
pcm.name {
type hw # カーネル PCM
card INT/STR # カード名 (文字列) or 番号 (整数)
[device INT] # デバイス番号 (デフォルトは0)
[subdevice INT] # サブデバイス番号 (デフォルトは-1で第一サブデバイスが有効)
[sync_ptr_ioctl BOOL] # Use SYNC_PTR ioctl rather than the direct mmap access for control structures
[nonblock BOOL] # non-blocking open モードを強制
[format STR] # 決められたフォーマットだけに制限
[channels INT] # 決められたチャンネルだけに制限
[rate INT] # 決められたレートだけに制限
}
pcm.name {
type mmap_emul
slave PCM
}
このプラグインは、共有メモリを介して aserver とコミュニケイトします。変換せず素のまま行いますが (
a raw communication without any conversions)、パフォーマンスが落ちる可能性があります。
pcm.name {
type shm # Shared memory PCM
server STR # サーバ名
pcm STR # ＰＣＭ名
}
このプラグインは、ＰＣＭストリームの中身を破棄してゼロサンプルのストリームを生成します。
注意： この実装は /dev/null (playback, must be writable)、 /dev/full (capture, must be readable) の各デバイスを使用します。
pcm.name {
type null # Null PCM
}
このプラグインは、マスターコピーＰＣＭから指定されたスレイブＰＣＭにサンプルをコピーします。チャンネル数、フォーマット、サンプリング・レートは、双方で一致している必要があります。
pcm.name {
type copy # Copy PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
}
}
このプラグインは、マスターのリニアＰＣＭからリニアサンプルをスレイブＰＣＭに変換します。双方のＰＣＭのチャンネル数、フォーマット、サンプリングレートは一致していなくてはいけません。
pcm.name {
type linear # Linear conversion PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
format STR # Slave format
}
}
このプラグインは、リニアサンプルから浮動小数点サンプルへ、もしくはその逆の変換を、マスターＰＣＭからスレイブPCMに対して行います。双方のＰＣＭのチャンネル数、フォーマット、サンプリングレートは一致していなくてはいけません。
pcm.name {
type lfloat # Linear<->Float conversion PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
format STR # Slave format
}
}
マスターの Mu-Law 変換ＰＣＭから所定のスレイブPCMに対して、Mu-Law サンプルからリニア、リニアから Mu-Law サンプルに変換します（
converts
Mu-Law samples to linear or linear to Mu-Law samples from master Mu-Law
conversion PCM to given slave PCM＝文章の構造がよく分からない…）。双方のＰＣＭのチャンネル数、フォーマット、サンプリングレートは一致していなくてはいけません。
pcm.name {
type mulaw # Mu-Law conversion PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
format STR # Slave format
}
}
マスターの A-Law 変換ＰＣＭから所定のスレイブPCMに対して、A-Law サンプルをリニアに、リニアを A-Law
サンプルに変換します（
converts A-Law samples to linear or linear to A-Law samples
from master A-Law conversion PCM to given slave
PCM）。双方のＰＣＭのチャンネル数、フォーマット、サンプリングレートは一致していなくてはいけません。
pcm.name {
type alaw # A-Law conversion PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
format STR # Slave format
}
}
マスターの Ima-ADPCM 変換ＰＣＭから所定のスレイブPCMに対して、Ima-ADPCM サンプルからリニア、リニアから Ima-ADPCM
サンプルに変換します（
converts Ima-ADPCM samples to linear or linear to Ima-ADPCM
samples from master Ima-ADPCM conversion PCM to given slave PCM）。双方のＰＣＭのチャンネル数、フォーマット、サンプリングレートは一致していなくてはいけません。
pcm.name {
type adpcm # Ima-ADPCM conversion PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
format STR # Slave format
}
}
複数のチャンネルを変換し、その際にボリウムを適用するプラグイン。フォーマットとサンプリングレートは一致していなくてはなりません。
pcm.name {
type route # Route & Volume conversion PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
[format STR] # Slave format
[channels INT] # Slave channels
}
ttable { # Transfer table (bi-dimensional compound of cchannels * schannels numbers)
CCHANNEL {
SCHANNEL REAL # route value (0.0 - 1.0)
}
}
}
ストリームのサンプリングレートを変換します。入力、出力ともにリニアＰＣＭである必要があります。
pcm.name {
type rate # Rate PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
rate INT # Slave rate
[format STR] # Slave format
}
converter STR # optional
# or
converter [ STR1 STR2 ... ] # optional
# Converter type, default is taken from
# defaults.pcm.rate_converter
}
チャンネル数、サンプリングレート、フォーマットを指定に応じて変換します。
pcm.name {
type plug # Automatic conversion PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
[format STR] # Slave format (default nearest) or "unchanged"
[channels INT] # Slave channels (default nearest) or "unchanged"
[rate INT] # Slave rate (default nearest) or "unchanged"
}
route_policy STR # route policy for automatic ttable generation
# STR can be 'default', 'average', 'copy', 'duplicate'
# average: result is average of input channels
# copy: only first channels are copied to destination
# duplicate: duplicate first set of channels
# default: copy policy, except for mono capture - sum
ttable { # Transfer table (bi-dimensional compound of cchannels * schannels numbers)
CCHANNEL {
SCHANNEL REAL # route value (0.0 - 1.0)
}
}
rate_converter STR # type of rate converter
# or
rate_converter [ STR1 STR2 ... ]
# type of rate converter
# default value is taken from defaults.pcm.rate_converter
}
- snd_pcm_plug_open()
- _snd_pcm_plug_open()
PCMストリームの内容をファイルに保存します。入力ソースとして実在するファイルを使うこともできます（例えば "virtual mic" のように）。
pcm.name {
type file # File PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
}
file STR # Output filename
or
file INT # Output file descriptor number
infile STR # Input filename
or
infile INT # Input file descriptor number
[format STR] # File format (only "raw" at the moment)
[perm INT] # Output file permission (octal, def. 0600)
}
複数のストリームをひとつに変換します。
pcm.name {
type multi # Multiple streams conversion PCM
slaves { # Slaves definition
ID STR # Slave PCM name
# or
ID {
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
channels INT # Slave channels
}
}
bindings { # Bindings table
N {
slave STR # Slave key
channel INT # Slave channel
}
}
[master INT] # Define the master slave
}
例えば、２chステレオである２つのＰＣＭストリームを１つの４chステレオのＰＣＭストリームにするには、次のように定義します。
pcm.quad {
type multi
slaves.a.pcm "hw:0,0"
slaves.a.channels 2
slaves.b.pcm "hw:0,1"
slaves.b.channels 2
bindings.0.slave a
bindings.0.channel 0
bindings.1.slave a
bindings.1.channel 1
bindings.2.slave b
bindings.2.channel 0
bindings.3.slave b
bindings.3.channel 1
}
結果として生成されるＰＣＭ「quad」は挟み込み形式（
the interleaved format）ではなく "複合体" 形式（
the "complex" format）であることに留意してください。この場合、挟み込み（あるいは非挟み込み）形式しか扱えないアプリケーションはこのPCMにアクセスすることができないので、そうしたければこのＰＣＭを
route プラグインか
plug プラグインでラップしてください。
pcm.quad2 {
type route
slave.pcm "quad"
ttable.0.0 1
ttable.1.1 1
ttable.2.2 1
ttable.3.3 1
}
複数の
チャンネル
（multiple channels）を複数のクライアントでシェアすることを可能にするプラグインです。各チャンネルへのアクセスは排他的で、各サンプルは互いにミックスされません。つまり、ch. 0が第１クライアントに使われている時、そのチャンネルは第２クライアントに使われることはありません。ミキシングのプラグインを探しているのなら、
dmix plugin. を使ってください。
dshare plugin との違いは、share プラグインがサーバプログラム "aserver" を必要としているのに対し、dshare プラグインは明示的なサーバを必要とせず共有バッファにアクセスする点です。
pcm.name {
type share # Share PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
[format STR] # Slave format
[channels INT] # Slave channels
[rate INT] # Slave rate
[period_time INT] # Slave period time in us
[buffer_time INT] # Slave buffer time in us
}
bindings {
N INT # Slave channel INT for client channel N
}
}
このプラグインは、プラグインが開かれた時・変更時・閉じた時に（
when this plugin is opened, modified or closed）、いくつかある 'hook' 関数を呼び出すのに使われます。何かの状態を示す制御値を変える時に〜特にＰＣＭに関して〜（
change control values for a certain state specially for the PCM）使われるのが典型例（以下の例を参照）。
# Hook arguments definition
hook_args.NAME {
... # Arbitrary arguments
}
# PCM hook type
pcm_hook_type.NAME {
[lib STR] # Library file (default libasound.so)
[install STR] # Install function (default _snd_pcm_hook_NAME_install)
}
# PCM hook definition
pcm_hook.NAME {
type STR # PCM Hook type (see pcm_hook_type)
[args STR] # Arguments for install function (see hook_args)
# or
[args { }] # Arguments for install function
}
# PCM hook plugin
pcm.NAME {
type hooks # PCM with hooks
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
}
hooks {
ID STR # Hook name (see pcm_hook)
# or
ID { } # Hook definition (see pcm_hook)
}
}
例えば :
hooks.0 {
type ctl_elems
hook_args [
{
name "Wave Surround Playback Volume"
preserve true
lock true
optional true
value [ 0 0 ]
}
{
name "EMU10K1 PCM Send Volume"
index { @func private_pcm_subdevice }
lock true
value [ 0 0 0 0 0 0 255 0 0 0 0 255 ]
}
]
}
ここでは、このＰＣＭにアクセスがあった時のコントロール "Wave Surround Playback Volume" とコントロール "EMU10K1 PCM Send Volume" について、所定の値が設定されています。これらのコントロールは複次元の値（
multi-dimensional value）を取るので、「
value 」フィールドは配列で表記されています。
「
preserve」が真（
true）の時は古い値は保存され、そのＰＣＭが閉じるときに復元されます。また「
lock」が true の時は、このＰＣＭが開いている間はコントロールがロックされ、ほかの何によっても変更されません。「
optional」が true にセットされたときは、そのコントロールが存在していなかった時でもエラーは返されず無視されます。
複数のストリームをダイレクトにミキシングする機能を提供します。32-bit ミキシングの解像度は 24-bit になります（The resolution for 32-bit mixing is only 24-bit）。低位の１バイトはゼロで埋められ、その余った 8bits （the low significant byte のこと？）は the saturation（浸透、浸潤、飽和…） に使われます。
pcm.name {
type dmix # Direct mix
ipc_key INT # unique IPC key
ipc_key_add_uid BOOL # add current uid to unique IPC key
ipc_perm INT # IPC permissions (octal, default 0600)
slave STR
# or
slave { # Slave definition
pcm STR # slave PCM name
# or
pcm { } # slave PCM definition
format STR # format definition
rate INT # rate definition
channels INT
period_time INT # in usec
# or
period_size INT # in bytes
buffer_time INT # in usec
# or
buffer_size INT # in bytes
periods INT # when buffer_size or buffer_time is not specified
}
bindings { # note: this is client independent!!!
N INT # maps slave channel to client channel N
}
slowptr BOOL # slow but more precise pointer updates
}
「ipc_key」は特定の IPC キーを整数で明示します。この数字は各 dmix 定義でユニーク（他と重複しない？）でなければなりません。この数字に従って共有メモリが生成されるからです。「ipc_key_add_uid 」が true にセットされているときは、 「ipc_key」の値のセットに uid 値が追加されます。
これによって、異なるユーザの同じ IPC キーが干渉しあうのを防ぎます。
dmix プラグイン自体は、単一のコンフィギュレーションのみをサポートします。つまり固定されたサンプリングレート（デフォルトは48000）、フォーマット（S16）、チャンネル数（2）、period_time(125000)をサポートするということです。他のコンフィギュレーションを使う場合は、スレイブＰＣＭの定義において値を明示的に設定してやる必要があります。サンプリングレート、フォーマット、チャンネル数は追加的なplug plugin がカバーしますが、いずれにせよ元になる唯一のコンフィギュレーションしか存在しないことに変わりはありません。
スレーブＰＣＭ "hw:0" に「サンプリングレート 44100 Hz - S32_LE フォーマット」を設定するコンフィギュレーションの例は、次のようなものになります。
pcm.dmix_44 {
type dmix
ipc_key 321456 # any unique value
ipc_key_add_uid true
slave {
pcm "hw:0"
format S32_LE
rate 44100
}
}
この dmix pcm を使えば、plug プラグインを介して 48000 Hz
のサンプルを聞くことも可能です（You can hear 48000 Hz samples still using this dmix pcm
via plug plugin like:）。
% aplay -Dplug:dmix_44 foo_48k.wav
OSS エミュレーション・デバイスに対して dmix plugin を使う時は、２の乗数で表記した「period_size」と「buffer size」を設定しなければいけません。例えば次のように。
pcm.dmixoss {
type dmix
ipc_key 321456 # any unique value
ipc_key_add_uid true
slave {
pcm "hw:0"
period_time 0
period_size 1024 # must be power of 2
buffer_size 8192 # ditto
}
}
デフォルト値をリセットするために「
period_time 0」も設定する必要があります。複数チャンネルのI/Oを持つサウンドカードの場合は、「bindings」を追加するといいでしょう。
pcm.dmixoss {
...
bindings {
0 0 # map from 0 to 0
1 1 # map from 1 to 1
}
}
こう定義すれば、dmix は最初の２チャンネルだけを使います。
それから、ICE1712 はバッファサイズに 5513 フレーム（640kB に相当）という上限があります。この場合は、「buffer_size」を「4096」に設定してやらなければなりません。
チャンネルを共有する機能を提供します（
provides sharing channels）。
share プラグインと異なるのは、 この dshare プラグインが明示的な（explicit）サーバ・プログラムを必要とせず、
dmix プラグインや
dsnoop プラグインと同じように各クライアントが同時に共有バッファにアクセスできる点です。以下に示すパラメータも、dmix / dsnoop とほとんど共通です。
pcm.name {
type dshare # Direct sharing
ipc_key INT # unique IPC key
ipc_key_add_uid BOOL # add current uid to unique IPC key
ipc_perm INT # IPC permissions (octal, default 0600)
slave STR
# or
slave { # Slave definition
pcm STR # slave PCM name
# or
pcm { } # slave PCM definition
format STR # format definition
rate INT # rate definition
channels INT
period_time INT # in usec
# or
period_size INT # in bytes
buffer_time INT # in usec
# or
buffer_size INT # in bytes
periods INT # when buffer_size or buffer_time is not specified
}
bindings { # note: this is client independent!!!
N INT # maps slave channel to client channel N
}
slowptr BOOL # slow but more precise pointer updates
}
ひとつのキャプチャストリームを複数に分けるプラグインで、dmix プラグインと逆の働きをします。複数のクライアントが並行して共有のキャプチャバッファを読むことになります（reading the shared capture buffer from many clients concurrently）。以下に示すパラメータは dmix プラグインのものとほとんど同じです。
pcm.name {
type dsnoop # Direct snoop
ipc_key INT # unique IPC key
ipc_key_add_uid BOOL # add current uid to unique IPC key
ipc_perm INT # IPC permissions (octal, default 0600)
slave STR
# or
slave { # Slave definition
pcm STR # slave PCM name
# or
pcm { } # slave PCM definition
format STR # format definition
rate INT # rate definition
channels INT
period_time INT # in usec
# or
period_size INT # in bytes
buffer_time INT # in usec
# or
buffer_size INT # in bytes
periods INT # when buffer_size or buffer_time is not specified
}
bindings { # note: this is client independent!!!
N INT # maps slave channel to client channel N
}
slowptr BOOL # slow but more precise pointer updates
}
このプラグインで、ワンセットの LADPSA プラグインを適用します。入出力のフォーマットは常に
SND_PCM_FORMAT_FLOAT です (注： この型はアーキテクチャによって little-endian と big-endian のどちらかをとります)。
「policy duplicate」が意味するところは、ch.0 (channel zero) に対して唯一の定義しか存在しない（there must be only one binding definition）、ということです。この定義は自動的に全てのチャンネルに複製されます。LADSPA プラグインが複数のオーディオ入出力（multiple audio inputs or outputs）を持っているときは、「policy duplicate」は自動的に「policy none」にスイッチします。
このプラグインのシリアル化（serialization）は期待どおりの働きを見せます。結局のところ、ALSA のプラグインチェインが処理するより多くの（複数の入出力）チャンネルを、この LADPSA プラグインチェインの中で使うことになるのです（use more channels (inputs / outputs) inside the LADPSA plugin chain than processed in the ALSA plugin chain）。
所与の LADSPA 入力ポートに対応する ALSA チャンネルが存在しなかった場合は、この LADSPA
ポートに対してはゼロサンプルが与えられます。出力側でも（ALSA の次のプラグイン入力）、有効なチャンネルがチェックされます。ある ALSAチャンネル（specific ALSA channel）が存在しなかった場合、LADSPA の出力ポートはダミーのサンプルエリアに接続されます。
LADSPA プラグインのインスタンスは動的に生成されるのです。
pcm.name {
type ladspa # ALSA<->LADSPA PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
}
[channels INT] # count input channels (input to LADSPA plugin chain)
[path STR] # Path (directory) with LADSPA plugins
plugins | # Definition for both directions
playback_plugins | # Definition for playback direction
capture_plugins { # Definition for capture direction
N { # Configuration for LADPSA plugin N
[id INT] # LADSPA plugin ID (for example 1043)
[label STR] # LADSPA plugin label (for example 'delay_5s')
[filename STR] # Full filename of .so library with LADSPA plugin code
[policy STR] # Policy can be 'none' or 'duplicate'
input | output {
bindings {
C INT or STR # C - channel, INT - audio port index, STR - audio port name
}
controls {
# valid only in the input block
I INT or REAL # I - control port index, INT or REAL - control value
# or
STR INT or REAL # STR - control port name, INT or REAL - control value
}
}
}
}
}
このプラグインは、ＰＣＭストリームの再生とキャプチャのコンビネーションです。スレイブＰＣＭは両方向で非対称に定義することができます（
Slave PCMs can be defined asymmetrically for both directions）。
pcm.name {
type asym # Asym PCM
playback STR # Playback slave name
# or
playback { # Playback slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
}
capture STR # Capture slave name
# or
capture { # Capture slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
}
}
例えば、 再生とキャプチャの向きそれぞれについて、dmix プラグインと dsnoop プラグインを単一のＰＣＭにひとまとめにすることが可能です（combine a dmix plugin and a dsnoop plugin as a single PCM for playback and capture directions, respectively）。
pcm.duplex {
type asym
playback.pcm "dmix"
capture.pcm "dsnoop"
}
なお、一方向だけを定義した時は、合成されたPCMは「half-duplex」になります。
32bit IEC958 サブフレームをリニアＰＣＭに、あるいはその逆の変換をします。
pcm.name {
type iec958 # IEC958 subframe conversion PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
}
[status status-bytes] # IEC958 status bits (given in byte array)
# IEC958 preamble bits definitions
# B/M/W or Z/X/Y, B = block start, M = even subframe, W = odd subframe
# As default, Z = 0x08, Y = 0x04, X = 0x02
[preamble.z or preamble.b val]
[preamble.x or preamble.m val]
[preamble.y or preamble.w val]
}
ソフトウェアによるボリウムの減衰ができます。ソースと出力先のフォーマット、サンプリングレート、チャンネル数は一致していなくてはなりません。
「control」が stereo （count 2）のケースでは、このチャンネルは モノ、2.0、2.1、4.0、4.1、5.1 あるいは 7.1 のいずれかであるである可能性がある、と推測されます（
assumed to be either...）。
その control が既に存在していてそれがシステムコントロールである場合（例えば no user-defined control）、このプラグインはスレイブを何の変更も加えることなくスルーします。
pcm.name {
type softvol # Soft Volume conversion PCM
slave STR # Slave name
# or
slave { # Slave definition
pcm STR # Slave PCM name
# or
pcm { } # Slave PCM definition
[format STR] # Slave format
}
control {
name STR # control element id string
[card STR] # control card index
[iface STR] # interface of the element
[index INT] # index of the element
[device INT] # device number of the element
[subdevice INT] # subdevice number of the element
[count INT] # control channels 1 or 2 (default: 2)
}
[min_dB REAL] # minimal dB value (default: -51.0)
[max_dB REAL] # maximal dB value (default: 0.0)
[resolution INT] # resolution (default: 256)
}
このプラグインは、ＰＣＭストリームの中身を破棄してゼロサンプルのストリームを生成します。
注意： この実装は /dev/null (playback, must be writable)、 /dev/full (capture, must be readable) の各デバイスを使用します。
pcm.name {
type null # Null PCM
}
----
(2007.11.19)
