1336 lines
35 KiB
HTML
1336 lines
35 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of AXFER-TRANSFER</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>AXFER-TRANSFER</H1>
|
|
Section: User Commands (1)<BR>Updated: 28 November 2018<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<P>
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
axfer-transfer - transferrer of audio data frame for sound devices and nodes.
|
|
<P>
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<P>
|
|
<B>axfer transfer</B>
|
|
|
|
<I>direction</I>
|
|
|
|
[
|
|
<I>common-options</I>
|
|
|
|
] [
|
|
<I>backend-options</I>
|
|
|
|
] [
|
|
<I>filepath</I>
|
|
|
|
]
|
|
<P>
|
|
<B>axfer transfer</B>
|
|
|
|
<I>direction</I>
|
|
|
|
[
|
|
<I>common-options</I>
|
|
|
|
] [
|
|
<I>backend-options</I>
|
|
|
|
]
|
|
<I>-I</I>
|
|
|
|
|
|
|
<I>--separate-channels filepath ...</I>
|
|
|
|
<P>
|
|
direction =
|
|
<B>capture</B>
|
|
|
|
|
|
|
<B>playback</B>
|
|
|
|
<P>
|
|
common-options = ( read
|
|
<I>OPTIONS</I>
|
|
|
|
section )
|
|
<P>
|
|
backend-options = ( read
|
|
<I>OPTIONS</I>
|
|
|
|
section )
|
|
<P>
|
|
filepaths = ( read
|
|
<I>OPTIONS</I>
|
|
|
|
section )
|
|
<P>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The
|
|
<B>transfer</B>
|
|
|
|
subcommand of
|
|
<B>axfer</B>
|
|
|
|
performs transmission of audio data frames for devices available in supported
|
|
backends. This program is essentially designed to use alsa-lib APIs
|
|
(libasound backend) to handle sound devices supported by Linux sound subsystem
|
|
(ALSA).
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<P>
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Direction</H3>
|
|
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="1"><B>capture</B>
|
|
|
|
<DD>
|
|
Operates for capture transmission.
|
|
<P>
|
|
<DT id="2"><B>playback</B>
|
|
|
|
<DD>
|
|
Operates for playback transmission.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Filepath</H3>
|
|
|
|
<P>
|
|
Filepath is handled as a path relative to current working directory of run time
|
|
if it's not full path from root directory.
|
|
<P>
|
|
The standard input or output is used if filepath is not specified or given as
|
|
<I>'-'</I>
|
|
|
|
.
|
|
<P>
|
|
For playback transmission, container format of given
|
|
<I>filepath</I>
|
|
|
|
is detected automatically and metadata is used for parameters of sample format,
|
|
channels, rate, duration. If nothing detected, content of given file path is
|
|
handled as raw data. In this case, the parameters should be indicated as
|
|
options.
|
|
<P>
|
|
Multiple
|
|
<I>filepaths</I>
|
|
|
|
are allowed with
|
|
<I>-I</I>
|
|
|
|
|
|
|
<I>--separate-channels</I>
|
|
|
|
option. In this case, standard input and output is not available. The same
|
|
<I>filepath</I>
|
|
|
|
is not allowed except for paths listed below:
|
|
<BR> - /dev/null
|
|
<BR> - /dev/zero
|
|
<BR> - /dev/full
|
|
<BR> - /dev/random
|
|
<BR> - /dev/urandom
|
|
<P>
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Common options</H3>
|
|
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="3"><B>-h, --help</B>
|
|
|
|
<DD>
|
|
Print help messages and finish run time.
|
|
<P>
|
|
<DT id="4"><B>-q, --quiet</B>
|
|
|
|
<DD>
|
|
Quiet mode. Suppress messages (not sound :))
|
|
<P>
|
|
<DT id="5"><B>-v, --verbose</B>
|
|
|
|
<DD>
|
|
Verbose mode. Runtime dumps supplemental information according to the number of
|
|
this option given in command line.
|
|
<P>
|
|
<DT id="6"><B>-d, --duration=#</B>
|
|
|
|
<DD>
|
|
Interrupt after # seconds. A value of zero means infinity. The default is zero,
|
|
so if this option is omitted then the transmission process will run until it is
|
|
killed. Either
|
|
<I>-d</I>
|
|
|
|
or
|
|
<I>-s</I>
|
|
|
|
option is available exclusively.
|
|
<P>
|
|
<DT id="7"><B>-s, --samples=#</B>
|
|
|
|
<DD>
|
|
Interrupt after transmission of # number of data frames. A value of zero means
|
|
infinity. The default is zero, so if this options is omitted then the
|
|
transmission process will run until it is killed. Either
|
|
<I>-d</I>
|
|
|
|
or
|
|
<I>-s</I>
|
|
|
|
option is available exclusively.
|
|
<P>
|
|
<DT id="8"><B>-f, --format=FORMAT</B>
|
|
|
|
<DD>
|
|
Indicate format of audio sample. This is required for capture transmission, or
|
|
playback transmission with files including raw audio data.
|
|
<P>
|
|
Available sample format is listed below:
|
|
<BR> - [S8|U8|S16|U16|S32|U32][_LE|_BE]
|
|
<BR> - [S24|U24][_LE|_BE]
|
|
<BR> - FLOAT[_LE|_BE]
|
|
<BR> - FLOAT64[_LE|_BE]
|
|
<BR> - IEC958_SUBFRAME[_LE|_BE]
|
|
<BR> - MU_LAW
|
|
<BR> - A_LAW
|
|
<BR> - [S20|U20][_LE|_BE]
|
|
<BR> - [S24|U24][_3LE|_3BE]
|
|
<BR> - [S20|U20][_3LE|_3BE]
|
|
<BR> - [S18|U18][_3LE|_3BE]
|
|
<BR> - DSD_U8
|
|
<BR> - DSD_[U16|U32][_LE|_BE]
|
|
<P>
|
|
If endian-ness is omitted, host endian-ness is used.
|
|
<P>
|
|
Some special formats are available:
|
|
<BR> - cd (16 bit little endian, 44100, stereo) [= -f S16_LE -c 2 -r 44100]
|
|
<BR> - cdr (16 bit big endian, 44100, stereo) [= -f S16_BE -c 2 -f 44100]
|
|
<BR> - dat (16 bit little endian, 48000, stereo) [= -f S16_LE -c 2 -r 48000]
|
|
<P>
|
|
If omitted,
|
|
<I>U8</I>
|
|
|
|
is used as a default. Actual available formats are restricted by each
|
|
transmission backend.
|
|
<P>
|
|
Unavailable sample format is listed below. These format has size of data frame
|
|
unaligned to byte unit.
|
|
<P>
|
|
<BR> - IMA_ADPCM
|
|
<BR> - MPEG
|
|
<BR> - GSM
|
|
<BR> - SPECIAL
|
|
<BR> - G723_24
|
|
<BR> - G723_24_1B
|
|
<BR> - G723_40
|
|
<BR> - G723_40_1B
|
|
<P>
|
|
<DT id="9"><B>-c, --channels=#</B>
|
|
|
|
<DD>
|
|
Indicate the number of audio data samples per frame. This is required for
|
|
capture transmission, or playback transmission with files including raw audio
|
|
data. The value should be between
|
|
<I>1 to</I>
|
|
|
|
<I>256</I>
|
|
|
|
. If omitted,
|
|
<I>1</I>
|
|
|
|
is used as a default.
|
|
<P>
|
|
<DT id="10"><B>-r, --rate=#</B>
|
|
|
|
<DD>
|
|
Indicate the number of audio data frame per second. This is required for
|
|
capture transmission, or playback transmission with files including raw audio
|
|
data. If the value is less than
|
|
<I>1000</I>
|
|
|
|
, it's interpreted by
|
|
<I>kHz</I>
|
|
|
|
unit. The value should be between
|
|
<I>2000</I>
|
|
|
|
and
|
|
<I>192000</I>
|
|
|
|
. If omitted,
|
|
<I>8000</I>
|
|
|
|
is used as a default.
|
|
<P>
|
|
<DT id="11"><B>-t, --file-type=TYPE</B>
|
|
|
|
<DD>
|
|
Indicate the type of file. This is required for capture transmission. Available
|
|
types are listed below:
|
|
<BR> - wav: Microsoft/IBM RIFF/Wave format
|
|
<BR> - au, sparc: Sparc AU format
|
|
<BR> - voc: Creative Tech. voice format
|
|
<BR> - raw: raw data
|
|
<P>
|
|
When nothing is indicated, for capture transmission, the type is decided
|
|
according to suffix of
|
|
<I>filepath</I>
|
|
|
|
, and
|
|
<I>raw</I>
|
|
|
|
type is used for fallback.
|
|
<P>
|
|
<DT id="12"><B>-I, --separate-channels</B>
|
|
|
|
<DD>
|
|
Indicate this option when several files are going to be handled. For capture
|
|
transmission, if one filepath is given as
|
|
<I>filepath</I>
|
|
|
|
, a list of
|
|
<I>filepaths</I>
|
|
|
|
is generated in a formula '<filepath>-<sequential number>[.suffix]'.
|
|
The suffix is omitted when raw format of container is used.
|
|
<P>
|
|
<DT id="13"><B>--dump-hw-params</B>
|
|
|
|
<DD>
|
|
Dump hardware parameters and finish run time if backend supports it.
|
|
<P>
|
|
<DT id="14"><B>--xfer-backend=BACKEND</B>
|
|
|
|
<DD>
|
|
Select backend of transmission from a list below. The default is libasound.
|
|
<BR>
|
|
|
|
<BR> - libasound
|
|
<BR> - libffado (optional if compiled)
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Backend options for libasound</H3>
|
|
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="15"><B>-D, --device=NODE</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option is used to select PCM node in libasound configuration space.
|
|
Available nodes are listed by
|
|
<I>pcm</I>
|
|
|
|
operation of
|
|
<I>list</I>
|
|
|
|
subcommand.
|
|
<P>
|
|
<DT id="16"><B>-N, --nonblock</B>
|
|
|
|
<DD>
|
|
<P>
|
|
With this option, PCM substream is opened in non-blocking mode. When audio
|
|
data frame is not available in buffer of the PCM substream, I/O operation
|
|
immediately returns without blocking process. This option implicitly uses
|
|
<I>--waiter-type</I>
|
|
|
|
option as well to prevent heavy consumption of CPU time.
|
|
<P>
|
|
<DT id="17"><B>-M, --mmap</B>
|
|
|
|
<DD>
|
|
<P>
|
|
With this option, audio data frame is processed directly in buffer of PCM
|
|
substream if selected node supports this operation. Without the option,
|
|
temporary buffers are used to copy audio data frame for buffer of PCM substream.
|
|
This option implicitly uses
|
|
<I>--waiter-type</I>
|
|
|
|
option as well to prevent heavy consumption of CPU time.
|
|
<P>
|
|
<DT id="18"><B>-F, --period-size=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option configures given value to
|
|
<I>period_size</I>
|
|
|
|
hardware parameter of PCM substream. The parameter indicates the number of audio
|
|
data frame per period in buffer of the PCM substream. Actual number is decided
|
|
as a result of interaction between each implementation of PCM plugin chained
|
|
from the selected PCM node, and in-kernel driver or PCM I/O plugins.
|
|
<P>
|
|
Ideally, the same amount of audio data frame as the value should be handled in
|
|
one I/O operation. Actually, it is not, depending on implementation of the PCM
|
|
plugins, in-kernel driver, PCM I/O plugins and scheduling model. For 'hw'
|
|
PCM plugin in 'irq' scheduling model, the value is used to decide
|
|
intervals of hardware interrupt, thus the same amount of audio data frame as
|
|
the value is expected to be available for one I/O operation.
|
|
<P>
|
|
<DT id="19"><B>--period-time=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option configures given value to
|
|
<I>period_time</I>
|
|
|
|
hardware parameter of PCM substream. This option is similar to
|
|
<I>--period-size</I>
|
|
|
|
option, however its unit is micro-second.
|
|
<P>
|
|
<DT id="20"><B>-B, --buffer-size=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option configures given value to
|
|
<I>buffer_size</I>
|
|
|
|
hardware parameter of PCM substream. The parameter indicates the number of audio
|
|
data frame in buffer of PCM substream. Actual number is decided as a result of
|
|
interaction between each implementation of PCM plugin chained from the selected
|
|
PCM node, and in-kernel driver or PCM I/O plugins.
|
|
<P>
|
|
Ideally, this is multiples of the number of audio data frame per period, thus
|
|
the size of period. Actually, it is not, depending on implementation of the PCM
|
|
plugins, in-kernel driver and PCM I/O plugins.
|
|
<P>
|
|
<DT id="21"><B>--buffer-time=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option configures given value to
|
|
<I>buffer_time</I>
|
|
|
|
hardware parameter of PCM substream. This option is similar to
|
|
<I>--buffer-size</I>
|
|
|
|
option, however its unit is micro-second.
|
|
<P>
|
|
<DT id="22"><B>--waiter-type=TYPE</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option indicates the type of waiter for event notification. At present,
|
|
four types are available;
|
|
<I>default</I>
|
|
|
|
,
|
|
<I>select</I>
|
|
|
|
,
|
|
<I>poll</I>
|
|
|
|
and
|
|
<I>epoll</I>
|
|
|
|
. With
|
|
<I>default</I>
|
|
|
|
type, 'snd_pcm_wait()' is used. With
|
|
<I>select</I>
|
|
|
|
type, '<A HREF="/cgi-bin/man/man2html?2+select">select</A>(2)' system call is used. With
|
|
<I>poll</I>
|
|
|
|
type, '<A HREF="/cgi-bin/man/man2html?2+poll">poll</A>(2)' system call is used. With
|
|
<I>epoll</I>
|
|
|
|
type, Linux-specific '<A HREF="/cgi-bin/man/man2html?7+epoll">epoll</A>(7)' system call is used.
|
|
<P>
|
|
This option should correspond to one of
|
|
<I>--nonblock</I>
|
|
|
|
or
|
|
<I>--mmap</I>
|
|
|
|
options, or
|
|
<I>timer</I>
|
|
|
|
value of
|
|
<I>--sched-model</I>
|
|
|
|
option.
|
|
Neither this option nor
|
|
<I>--test-nowait</I>
|
|
|
|
is available at the same time.
|
|
<P>
|
|
<DT id="23"><B>--sched-model=MODEL</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option selects scheduling model for process of this program. One of
|
|
<I>irq</I>
|
|
|
|
or
|
|
<I>timer</I>
|
|
|
|
is available. In detail, please read 'SCHEDULING MODEL' section.
|
|
<P>
|
|
When nothing specified,
|
|
<I>irq</I>
|
|
|
|
model is used.
|
|
<P>
|
|
<DT id="24"><B>-A, --avail-min=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option configures given value to
|
|
<I>avail-min</I>
|
|
|
|
software parameter of PCM substream. In blocking mode, the value is used as
|
|
threshold of the number of available audio data frames in buffer of PCM
|
|
substream to wake up process blocked by I/O operation. In non-blocking mode,
|
|
any I/O operation returns -EAGAIN untill the available number of audio data frame reaches the threshold.
|
|
<P>
|
|
This option has an effect in cases neither
|
|
<I>--mmap</I>
|
|
|
|
nor
|
|
<I>timer</I>
|
|
|
|
value of
|
|
<I>--sched-model</I>
|
|
|
|
option is used.
|
|
<P>
|
|
<DT id="25"><B>-R, --start-delay=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option configures given value to
|
|
<I>start_threshold</I>
|
|
|
|
software parameter of PCM substream. The value is used as threshold to start
|
|
PCM substream automatically. At present, this option has an effect in cases
|
|
neither
|
|
<I>--mmap</I>
|
|
|
|
nor
|
|
<I>timer</I>
|
|
|
|
value of
|
|
<I>--sched-model</I>
|
|
|
|
option is used.
|
|
<P>
|
|
For playback transmission, when the number of accumulated audio data frame
|
|
in buffer of PCM substream to which this program writes out reaches the
|
|
threshold, the PCM substream starts automatically without an explicit call of
|
|
<I>snd_pcm_start()</I>
|
|
|
|
to the PCM substream.
|
|
<P>
|
|
For capture transmission, this option is useless. The number of
|
|
accumulated audio data frame is not increased without an explicit call of
|
|
<I>snd_pcm_start()</I>
|
|
|
|
to the PCM substream.
|
|
<P>
|
|
This option has an effect in cases neither
|
|
<I>--mmap</I>
|
|
|
|
nor
|
|
<I>timer</I>
|
|
|
|
value of
|
|
<I>--sched-model</I>
|
|
|
|
option is used.
|
|
<P>
|
|
<DT id="26"><B>-T, --stop-delay=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option configures given value to
|
|
<I>stop_threshold</I>
|
|
|
|
software parameter of PCM substream. The value is used as threshold to stop PCM
|
|
substream automatically. At present, this option has an effect in cases neither
|
|
<I>--mmap</I>
|
|
|
|
nor
|
|
<I>timer</I>
|
|
|
|
value of
|
|
<I>--sched-model</I>
|
|
|
|
option is used.
|
|
<P>
|
|
For capture transmission, when the number of accumulated audio data frame
|
|
in buffer of PCM substream to which a driver or alsa-lib PCM plugins write
|
|
reaches the threshold, the PCM substream stops automatically without an explicit
|
|
call of
|
|
<I>snd_pcm_stop()</I>
|
|
|
|
to the PCM substream. This is a case that this program leaves the audio data
|
|
frames without reading for a while.
|
|
<P>
|
|
For playback transmission, when the number available audio data frame in buffer
|
|
of PCM substream from which a driver or alsa-lib PCM plugins read reaches the
|
|
threshold, the PCM substream stops automatically without an explicit call of
|
|
<I>snd_pcm_stop()</I>
|
|
|
|
to the PCM substream. This is a case that this program leaves the audio data
|
|
frames without writing for a while.
|
|
<P>
|
|
This option has an effect in cases neither
|
|
<I>--mmap</I>
|
|
|
|
nor
|
|
<I>timer</I>
|
|
|
|
value of
|
|
<I>--sched-model</I>
|
|
|
|
option is used.
|
|
<P>
|
|
<DT id="27"><B>--disable-resample</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option has an effect for 'plug' plugin in alsa-lib to suppress
|
|
conversion of sampling rate for audio data frame.
|
|
<P>
|
|
<DT id="28"><B>--disable-channels</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option has an effect for 'plug' plugin in alsa-lib to suppress
|
|
conversion of channels for audio data frame.
|
|
<P>
|
|
<DT id="29"><B>--disable-format</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option has an effect for 'plug' plugin in alsa-lib to suppress
|
|
conversion of sample format for audio data frame.
|
|
<P>
|
|
<DT id="30"><B>--disable-softvol</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option has an effect for 'softvol' plugin in alsa-lib to suppress
|
|
conversion of samples for audio data frame via additional control element.
|
|
<P>
|
|
<DT id="31"><B>--fatal-errors</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option suppresses recovery operation from XRUN state of running PCM
|
|
substream, then process of this program is going to finish as usual.
|
|
<P>
|
|
<DT id="32"><B>--test-nowait</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option disables any waiter for I/O event notification. I/O operations are
|
|
iterated till any of audio data frame is available. The option brings heavy
|
|
load in consumption of CPU time.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Backend options for libffado</H3>
|
|
|
|
<P>
|
|
This backend is automatically available when configure script detects
|
|
<I>ffado_streaming_init()</I>
|
|
|
|
symbol in libffado shared object.
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="33"><B>-p, --port=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option uses given value to decide which 1394 OHCI controller is used to
|
|
communicate. When Linux system has two 1394 OHCI controllers,
|
|
<I>0</I>
|
|
|
|
or
|
|
<I>1</I>
|
|
|
|
are available. Neither this option nor
|
|
<I>-g</I>
|
|
|
|
is available at the same time. If nothing specified, libffado performs to
|
|
communicate to units on IEEE 1394 bus managed by all of 1394 OHCI controller available in Linux system.
|
|
<P>
|
|
<DT id="34"><B>-n, --node=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option uses given value to decide which unit is used to communicate. This
|
|
option requires
|
|
<I>-p</I>
|
|
|
|
option to indicate which 1394 OHCI controller is used to communicate to the
|
|
specified unit.
|
|
<P>
|
|
<DT id="35"><B>-g, --guid=HEXADECIMAL</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option uses given value to decide a target unit to communicate. The value
|
|
should be prefixed with '0x' and consists of hexadecimal literal letters
|
|
(0-9, a-f, A-F). Neither this option nor
|
|
<I>-p</I>
|
|
|
|
is available at the same time. If nothing specified, libffado performs to
|
|
communicate to units on IEEE 1394 bus managed by all of 1394 OHCI controller
|
|
available in Linux system.
|
|
<P>
|
|
<DT id="36"><B>--frames-per-period=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option uses given value to decide the number of audio data frame in one
|
|
read/write operation. The operation is blocked till the number of available
|
|
audio data frame exceeds the given value. As a default, 512 audio data frames
|
|
is used.
|
|
<P>
|
|
<DT id="37"><B>--periods-per-buffer=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option uses given value to decide the size of intermediate buffer between
|
|
this program and libffado. As a default, 2 periods per buffer is used.
|
|
<P>
|
|
<DT id="38"><B>--slave</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option allows this program to run slave mode. In this mode, libffado
|
|
adds unit directory into configuration ROM of 1394 OHCI controller where Linux
|
|
system runs. The unit directory can be found by the other node on the same bus.
|
|
Linux system running on the node can transfer isochronous packet with audio
|
|
data frame to the unit. This program can receive the packet and demultiplex the
|
|
audio data frame.
|
|
<P>
|
|
<DT id="39"><B>--snoop</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option allows this program to run snoop mode. In this mode, libffado
|
|
listens isochronous channels to which device transfers isochronous packet. When
|
|
isochronous communication starts by any unit on the same bus, the packets can
|
|
be handled by this program.
|
|
<P>
|
|
<DT id="40"><B>--sched-priority=#</B>
|
|
|
|
<DD>
|
|
<P>
|
|
This option executes
|
|
<I>pthread_setschedparam()</I>
|
|
|
|
in a call of
|
|
<I>ffado_streaming_init()</I>
|
|
|
|
to configure
|
|
scheduling policy and given value as its priority for threads related to
|
|
isochronous communication.
|
|
The given value should be within
|
|
<I>RLIMIT_RTPRIO</I>
|
|
|
|
parameter of process. Please read
|
|
<I><A HREF="/cgi-bin/man/man2html?2+getrlimit">getrlimit</A>(2)</I>
|
|
|
|
for details.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>POSIX SIGNALS</H2>
|
|
|
|
During transmission,
|
|
<I>SIGINT</I>
|
|
|
|
and
|
|
<I>SIGTERM</I>
|
|
|
|
will close handled files and PCM substream to be going to finish run time.
|
|
<P>
|
|
<I>SIGTSTP</I>
|
|
|
|
will suspend PCM substream and
|
|
<I>SIGCONT</I>
|
|
|
|
will resume it. No XRUNs are expected. With libffado backend, the suspend/resume
|
|
is not supported and runtime is aboeted immediately.
|
|
<P>
|
|
The other signals perform default behaviours.
|
|
<P>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
|
|
|
|
<B>$ axfer transfer playback -d 1 something</B>
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<P>
|
|
The above will transfer audio data frame in 'something' file for playback
|
|
during 1 second. The sample format is detected automatically as a result to
|
|
parse 'something' as long as it's compliant to one of Microsoft/IBM
|
|
RIFF/Wave, Sparc AU, Creative Tech. voice formats. If nothing detected,
|
|
<I>-r</I>
|
|
|
|
,
|
|
<I>-c</I>
|
|
|
|
and
|
|
<I>-f</I>
|
|
|
|
should be given,
|
|
or
|
|
<I>-f</I>
|
|
|
|
should be given with special format.
|
|
<P>
|
|
<P>
|
|
|
|
|
|
|
|
<B>$ axfer transfer playback -r 22050 -c 1 -f S16_LE -t raw something</B>
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<P>
|
|
The above will transfer audio data frame in 'something' file including no
|
|
information of sample format, as sample format of 22050 Hz, monaural, signed 16
|
|
bit little endian PCM for playback. The transmission continues till catching
|
|
<I>SIGINT</I>
|
|
|
|
from keyboard or
|
|
<I>SIGTERM</I>
|
|
|
|
by
|
|
<I><A HREF="/cgi-bin/man/man2html?1+kill">kill</A>(1)</I>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
|
|
|
|
|
|
<B>$ axfer transfer capture -d 10 -f cd something.wav</B>
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<P>
|
|
The above will transfer audio data frame to 'something.wav' file as
|
|
sample format of 44.1 kHz, 2 channels, signed 16 bit little endian PCM, during
|
|
10 seconds. The file format is Microsoft/IBM RIFF/Wave according to suffix of
|
|
the given
|
|
<I>filepath</I>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
|
|
|
|
|
|
<B>$ axfer transfer capture -s 1024 -r 48000 -c 2 -f S32_BE -I -t au channels</B>
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<P>
|
|
The above will transfer audio data frame as sample format of 48.0 kHz, 2
|
|
channels, signed 32 bit big endian PCM for 1,024 number of data frames to files
|
|
named 'channels-1.au' and 'channels-2.au'.
|
|
<P>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>SCHEDULING MODEL</H2>
|
|
|
|
<P>
|
|
In a design of ALSA PCM core, runtime of PCM substream supports two modes;
|
|
<I>period-wakeup</I>
|
|
|
|
and
|
|
<I>no-period-wakeup.</I>
|
|
|
|
These two modes are for different scheduling models.
|
|
<P>
|
|
<A NAME="lbAN"> </A>
|
|
<H3>IRQ-based scheduling model</H3>
|
|
|
|
<P>
|
|
As a default,
|
|
<I>period-wakeup</I>
|
|
|
|
mode is used. In this mode, in-kernel drivers should operate hardware to
|
|
generate periodical notification for transmission of audio data frame. The
|
|
interval of notification is equivalent to the same amount of audio data frame
|
|
as one period of buffer, against actual time.
|
|
<P>
|
|
In a handler assigned to the notification, a helper function of ALSA PCM core
|
|
is called to update a position to head of hardware transmission, then compare
|
|
it with a position to head of application operation to judge overrun/underrun
|
|
(XRUN) and to wake up blocked processes.
|
|
<P>
|
|
For this purpose, hardware IRQ of controller for serial audio bus such as
|
|
Inter-IC sound is typically used. In this case, the controller generates the
|
|
IRQ according to transmission on the serial audio bus. In the handler assigned
|
|
to the IRQ, direct media access (DMA) transmission is requested between
|
|
dedicated host memory and device memory.
|
|
<P>
|
|
If target hardware doesn't support this kind of mechanism, the periodical
|
|
notification should be emulated by any timer; e.g. hrtimer, kernel timer.
|
|
External PCM plugins generated by PCM plugin SDK in alsa-lib should also
|
|
emulate the above behaviour.
|
|
<P>
|
|
In this mode, PCM applications are programmed according to typical way of I/O
|
|
operations. They execute blocking system calls to read/write audio data frame
|
|
in buffer of PCM substream, or blocking system calls to wait until any audio
|
|
data frame is available. In
|
|
<I>axfer</I>
|
|
|
|
, this is called
|
|
<I>IRQ-based</I>
|
|
|
|
scheduling model and a default behaviour. Users can explicitly configure this
|
|
mode by usage of
|
|
<I>--sched-model</I>
|
|
|
|
option with
|
|
<I>irq</I>
|
|
|
|
value.
|
|
<P>
|
|
<A NAME="lbAO"> </A>
|
|
<H3>Timer-based scheduling model</H3>
|
|
|
|
<P>
|
|
The
|
|
<I>no-period-wakeup</I>
|
|
|
|
mode is an optional mode of runtime of PCM substream. The mode assumes a
|
|
specific feature of hardware and assist of in-kernel driver and PCM
|
|
applications. In this mode, in-kernel drivers don't operate hardware to
|
|
generate periodical notification for transmission of audio data frame.
|
|
The hardware should automatically continue transmission of audio data frame
|
|
without periodical operation of the drivers; e.g. according to auto-triggered
|
|
DMA transmission, a chain of registered descriptors.
|
|
<P>
|
|
In this mode, nothing wakes up blocked processes, therefore PCM applications
|
|
should be programmed without any blocking operation. For this reason, this mode
|
|
is enabled when the PCM applications explicitly configure hardware parameter to
|
|
runtime of PCM substream, to prevent disorder of existing applications.
|
|
Additionally, nothing maintains timing for transmission of audio data frame,
|
|
therefore the PCM applications should voluntarily handle any timer to queue
|
|
audio data frame in buffer of the PCM substream for lapse of time. Furthermore,
|
|
instead of driver, the PCM application should call a helper function of ALSA
|
|
PCM core to update a position to head of hardware transmission and to check
|
|
XRUN.
|
|
<P>
|
|
In
|
|
<I>axfer</I>
|
|
|
|
, this is called
|
|
<I>timer-based</I>
|
|
|
|
scheduling model and available as long as hardware/driver assists
|
|
<I>no-period-wakeup</I>
|
|
|
|
runtime. Users should explicitly set this mode by usage of
|
|
<I>--sched-model</I>
|
|
|
|
option with
|
|
<I>timer</I>
|
|
|
|
value.
|
|
<P>
|
|
In the scheduling model, PCM applications need to care of available space on
|
|
PCM buffer by lapse of time, typically by yielding CPU and wait for
|
|
rescheduling. For the yielding, timeout is calculated for preferable amount of
|
|
PCM frames to process. This is convenient to a kind of applications, like sound
|
|
servers. when an I/O thread of the server wait for the timeout, the other
|
|
threads can process audio data frames for server clients. Furthermore, with
|
|
usage of rewinding/forwarding, applications can achieve low latency between
|
|
transmission position and handling position even if they uses large size of
|
|
PCM buffers.
|
|
<P>
|
|
<A NAME="lbAP"> </A>
|
|
<H3>Advantages and issues</H3>
|
|
|
|
<P>
|
|
Ideally, timer-based scheduling model has some advantages than IRQ-based
|
|
scheduling model. At first, no interrupt context runs for PCM substream. The
|
|
PCM substream is handled in any process context only. No need to care of race
|
|
conditions between IRQ and process contexts. This reduces some concerns for
|
|
some developers of drivers and applications. Secondary, CPU time is not used
|
|
for handlers on the interrupt context. The CPU time can be dedicated for the
|
|
other tasks. This is good in a point of Time Sharing System. Thirdly, hardware
|
|
is not configured to generate interrupts. This is good in a point of reduction
|
|
of overall power consumption possibly.
|
|
<P>
|
|
In either scheduling model, the hardware should allow drivers to read the
|
|
number of audio data frame transferred between the dedicated memory and the
|
|
device memory for audio serial bus. However, in timer-based scheduling model,
|
|
fine granularity and accuracy of the value is important. Actually hardware
|
|
performs transmission between dedicated memory and device memory for a small
|
|
batch of audio data frames or bytes. In a view of PCM applications, the
|
|
granularity in current transmission is required to decide correct timeout for
|
|
each I/O operation. As of Linux kernel v4.21, ALSA PCM interface between
|
|
kernel/userspace has no feature to report it.
|
|
<P>
|
|
<A NAME="lbAQ"> </A>
|
|
<H2>COMPATIBILITY TO APLAY</H2>
|
|
|
|
<P>
|
|
The
|
|
<B>transfer</B>
|
|
|
|
subcommand of
|
|
<B>axfer</B>
|
|
|
|
is designed to keep compatibility to <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1). However some options below are
|
|
not compatible due to several technical reasons.
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="41"><I>-I, --separate-channels</I>
|
|
|
|
<DD>
|
|
This option is supported just for files to store audio data frames corresponding
|
|
to each channel. In <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, this option has an additional
|
|
effect to use PCM buffer aligned to non-interleaved order if a target device
|
|
supports. As of 2018, PCM buffer of non-interleaved order is hardly used by
|
|
sound devices.
|
|
<P>
|
|
<DT id="42"><I>-A, --avail-min=#</I>
|
|
|
|
<DD>
|
|
This option indicates threshold to wake up blocked process in a unit of
|
|
audio data frame. Against <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, this option has no effect
|
|
with
|
|
<I>--mmap</I>
|
|
|
|
option as well as
|
|
<I>timer</I>
|
|
|
|
of
|
|
<I>--sched-model</I>
|
|
|
|
option.
|
|
<P>
|
|
<DT id="43"><I>-R, --start-delay=#</I>
|
|
|
|
<DD>
|
|
This option indicates threshold to start prepared PCM substream in a unit of
|
|
audio data frame. Against <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, this option has no effect
|
|
with
|
|
<I>--mmap</I>
|
|
|
|
option as well as
|
|
<I>timer</I>
|
|
|
|
of
|
|
<I>--sched-model</I>
|
|
|
|
option.
|
|
<P>
|
|
<DT id="44"><I>-T, --stop-delay=#</I>
|
|
|
|
<DD>
|
|
This option indicates threshold to stop running PCM substream in a unit of
|
|
audio data frame. Against <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, this option has no effect
|
|
with
|
|
<I>--mmap</I>
|
|
|
|
option as well as
|
|
<I>timer</I>
|
|
|
|
of
|
|
<I>--sched-model</I>
|
|
|
|
option.
|
|
<P>
|
|
<DT id="45"><I>--max-file-time=#</I>
|
|
|
|
<DD>
|
|
This option is unsupported. In <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, the option has an
|
|
effect for capture transmission to save files up to the same number of data
|
|
frames as the given value by second unit, or the maximum number of data frames
|
|
supported by used file format. When reaching to the limitation, used file is
|
|
closed, then new file is opened and audio data frames are written. However, this
|
|
option requires extra handling of files and shall increase complexity of main
|
|
loop of axfer.
|
|
<P>
|
|
<DT id="46"><I>--use-strftime=FORMAT</I>
|
|
|
|
<DD>
|
|
This option is unsupported. In <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, the option has an effect
|
|
for capture transmission to generate file paths according to given format in
|
|
which some extra formats are available as well as formats supported by
|
|
<A HREF="/cgi-bin/man/man2html?3+strftime">strftime</A>(3). However, this option requires extra string processing for file
|
|
paths and it's bothersome if written in C language.
|
|
<P>
|
|
<DT id="47"><I>--process-id-file=FILEPATH</I>
|
|
|
|
<DD>
|
|
This option is unsupported. In <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, the option has an effect
|
|
to create a file for given value and write out process ID to it. This file
|
|
allows users to get process ID and send any POSIX signal to aplay process.
|
|
However, this idea has some troubles for file locking when multiple aplay
|
|
processes run with the same file.
|
|
<P>
|
|
<DT id="48"><I>-V, --vumeter=TYPE</I>
|
|
|
|
<DD>
|
|
This option is not supported at present. In <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, this option
|
|
has an effect to occupy stdout with some terminal control characters and display
|
|
vumeter for monaural and stereo channels. However, some problems lay; this
|
|
feature is just for audio data frames with PCM format, this feature brings
|
|
disorder of terminal after aborting, stdout is not available for pipeline.
|
|
<P>
|
|
<DT id="49"><I>-i, --interactive</I>
|
|
|
|
<DD>
|
|
This option is not supported at present. In <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, this option
|
|
has an effect to occupy stdin for key input and suspend/resume PCM substream
|
|
according to pushed enter key. However, this feature requires an additional
|
|
input handling in main loop and leave bothersome operation to maintain PCM
|
|
substream.
|
|
<P>
|
|
<DT id="50"><I>-m, --chmap=CH1,CH2,...</I>
|
|
|
|
<DD>
|
|
ALSA PCM core and control core doesn't support this feature, therefore
|
|
remapping should be done in userspace. This brings overhead to align audio
|
|
data frames, especially for mmap operation. Furthermore, as of alsa-lib v1.1.8,
|
|
some plugins don't support this feature expectedly, thus this option is a lack
|
|
of transparent operation. At present, this option is not supported yet not to
|
|
confuse users.
|
|
<P>
|
|
<DT id="51"><I>SIGTSTP, SIGCONT</I>
|
|
|
|
<DD>
|
|
This performs suspend/resume of PCM substream. In <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation,
|
|
these operations bring XRUN state to the substream, and suspend/resume is done
|
|
in interactive mode in the above. Some developers use the signal for recovery
|
|
test from XRUN. At present, no alternative is supported for the test.
|
|
<P>
|
|
<DT id="52"><I>SIGUSR1</I>
|
|
|
|
<DD>
|
|
This is not supported. In <A HREF="/cgi-bin/man/man2html?1+aplay">aplay</A>(1) implementation, this signal is assigned to a
|
|
handler to close a current file to store audio data frame and open a new file
|
|
to continue processing. However, as well as
|
|
<I>--max-file-time</I>
|
|
|
|
option, this option should increase complexity of main loop of axfer.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAR"> </A>
|
|
<H2>DESIGN</H2>
|
|
|
|
<P>
|
|
<A NAME="lbAS"> </A>
|
|
<H3>Modular structure</H3>
|
|
|
|
<P>
|
|
This program consists of three modules;
|
|
<I>xfer</I>
|
|
|
|
,
|
|
<I>mapper</I>
|
|
|
|
and
|
|
<I>container</I>
|
|
|
|
.
|
|
Each module has an abstraction layer to enable actual implementation.
|
|
<P>
|
|
<PRE>
|
|
-------- ---------- -------------
|
|
device <-> | xfer | <-> | mapper | <-> | container | <-> file
|
|
-------- ---------- -------------
|
|
libasound single wav
|
|
libffado multiple au
|
|
voc
|
|
raw
|
|
</PRE>
|
|
|
|
<P>
|
|
The
|
|
<I>xfer</I>
|
|
|
|
module performs actual transmission to devices and nodes. The module can have
|
|
several transmission backends. As a default backend,
|
|
<I>libasound</I>
|
|
|
|
backend is used to perform transmission via alsa-lib APIs. The module allows
|
|
each backend to parse own command line options.
|
|
<P>
|
|
The
|
|
<I>container</I>
|
|
|
|
module performs to read/write audio data frame via descriptor for file/stream
|
|
of multimedia container or raw data. The module automatically detect type of
|
|
multimedia container and parse parameters in its metadata of data header. At
|
|
present, three types of multimedia containers are supported; Microsoft/IBM
|
|
RIFF/Wave (
|
|
<I>wav</I>
|
|
|
|
), Sparc AU (
|
|
<I>au</I>
|
|
|
|
) and Creative Technology voice (
|
|
<I>voc</I>
|
|
|
|
). Additionally, a special container is prepared for raw audio data (
|
|
<I>raw</I>
|
|
|
|
).
|
|
<P>
|
|
The
|
|
<I>mapper</I>
|
|
|
|
module handles buffer layout and alignment for transmission of audio data frame.
|
|
The module has two implementations;
|
|
<I>single</I>
|
|
|
|
and
|
|
<I>multiple</I>
|
|
|
|
.
|
|
The
|
|
<I>single</I>
|
|
|
|
backend uses one container to construct the buffer. The
|
|
<I>multiple</I>
|
|
|
|
backend uses several containers to construct it.
|
|
<P>
|
|
<A NAME="lbAT"> </A>
|
|
<H3>Care of copying audio data frame</H3>
|
|
|
|
<P>
|
|
Between the
|
|
<I>xfer</I>
|
|
|
|
module and
|
|
<I>mapper</I>
|
|
|
|
module, a pointer to buffer including audio data frames is passed. This buffer
|
|
has two shapes for interleaved and non-interleaved order. For the former, the
|
|
pointer points to one buffer. For the latter, the pointer points to an array in
|
|
which each element points to one buffer. Between the
|
|
<I>mapper</I>
|
|
|
|
module and
|
|
<I>container</I>
|
|
|
|
module, a pointer to one buffer is passed because supported media containers
|
|
including raw type store audio data frames in interleaved order.
|
|
<P>
|
|
In passing audio data frame between the modules, axfer is programmed to avoid
|
|
copying between a buffer to another buffer as much as possible. For example, in
|
|
some scenarios below, no copying occurs between modules.
|
|
<P>
|
|
<BR> - xfer(mmap/interleaved), mapper(single), container(any)
|
|
<BR> - xfer(mmap/non-interleaved), mapper(multiple), containers(any)
|
|
<P>
|
|
<A NAME="lbAU"> </A>
|
|
<H3>Unit test</H3>
|
|
|
|
<P>
|
|
For each of the
|
|
<I>mapper</I>
|
|
|
|
and
|
|
<I>container</I>
|
|
|
|
module, unit test is available. To run the tests, execute below command:
|
|
<P>
|
|
<PRE>
|
|
$ make test
|
|
</PRE>
|
|
|
|
<P>
|
|
Each test iterates writing to file and reading to the file for many times and it
|
|
takes long time to finish. Please take care of the execution time if running on
|
|
any CI environment.
|
|
<P>
|
|
<A NAME="lbAV"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B>
|
|
<A HREF="/cgi-bin/man/man2html?1+axfer">axfer</A>(1),
|
|
<A HREF="/cgi-bin/man/man2html?1+axfer-list">axfer-list</A>(1),
|
|
<A HREF="/cgi-bin/man/man2html?1+alsamixer">alsamixer</A>(1),
|
|
<A HREF="/cgi-bin/man/man2html?1+amixer">amixer</A>(1)
|
|
</B>
|
|
<P>
|
|
<A NAME="lbAW"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
Takashi Sakamoto <<A HREF="mailto:o-takashi@sakamocchi.jp">o-takashi@sakamocchi.jp</A>>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="53"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="54"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="55"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="56"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DL>
|
|
<DT id="57"><A HREF="#lbAF">Direction</A><DD>
|
|
<DT id="58"><A HREF="#lbAG">Filepath</A><DD>
|
|
<DT id="59"><A HREF="#lbAH">Common options</A><DD>
|
|
<DT id="60"><A HREF="#lbAI">Backend options for libasound</A><DD>
|
|
<DT id="61"><A HREF="#lbAJ">Backend options for libffado</A><DD>
|
|
</DL>
|
|
<DT id="62"><A HREF="#lbAK">POSIX SIGNALS</A><DD>
|
|
<DT id="63"><A HREF="#lbAL">EXAMPLES</A><DD>
|
|
<DT id="64"><A HREF="#lbAM">SCHEDULING MODEL</A><DD>
|
|
<DL>
|
|
<DT id="65"><A HREF="#lbAN">IRQ-based scheduling model</A><DD>
|
|
<DT id="66"><A HREF="#lbAO">Timer-based scheduling model</A><DD>
|
|
<DT id="67"><A HREF="#lbAP">Advantages and issues</A><DD>
|
|
</DL>
|
|
<DT id="68"><A HREF="#lbAQ">COMPATIBILITY TO APLAY</A><DD>
|
|
<DT id="69"><A HREF="#lbAR">DESIGN</A><DD>
|
|
<DL>
|
|
<DT id="70"><A HREF="#lbAS">Modular structure</A><DD>
|
|
<DT id="71"><A HREF="#lbAT">Care of copying audio data frame</A><DD>
|
|
<DT id="72"><A HREF="#lbAU">Unit test</A><DD>
|
|
</DL>
|
|
<DT id="73"><A HREF="#lbAV">SEE ALSO</A><DD>
|
|
<DT id="74"><A HREF="#lbAW">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:07 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|