.TH AXFER\-TRANSFER 1 "28 November 2018" "alsa\-utils" .SH NAME axfer\-transfer \- transferrer of audio data frame for sound devices and nodes. .SH SYNOPSIS .B axfer transfer .I direction [ .I common\-options ] [ .I backend\-options ] [ .I filepath ] .B axfer transfer .I direction [ .I common\-options ] [ .I backend\-options ] .I \-I | .I \-\-separate\-channels filepath ... direction = .B capture | .B playback common\-options = ( read .I OPTIONS section ) backend\-options = ( read .I OPTIONS section ) filepaths = ( read .I OPTIONS section ) .SH DESCRIPTION The .B transfer subcommand of .B axfer 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). .SH OPTIONS .SS Direction .TP .B capture Operates for capture transmission. .TP .B playback Operates for playback transmission. .SS Filepath Filepath is handled as a path relative to current working directory of run time if it\(aqs not full path from root directory. The standard input or output is used if filepath is not specified or given as .I \(aq\-\(aq \&. For playback transmission, container format of given \I filepath 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. Multiple .I filepaths are allowed with .I \-I | .I \-\-separate\-channels option. In this case, standard input and output is not available. The same .I filepath is not allowed except for paths listed below: \- /dev/null \- /dev/zero \- /dev/full \- /dev/random \- /dev/urandom .SS Common options .TP .B \-h, \-\-help Print help messages and finish run time. Not yet implemented. .TP .B \-q, \-\-quiet Quiet mode. Suppress messages (not sound :)) .TP .B \-v, \-\-verbose Verbose mode. Runtime dumps supplemental information according to the number of this option given in command line. .TP .B \-d, \-\-duration=# 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 or .I \-s option is available exclusively. .TP .B \-s, \-\-samples=# 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 or .I \-s option is available exclusively. .TP .B \-f, \-\-format=FORMAT Indicate format of audio sample. This is required for capture transmission, or playback transmission with files including raw audio data. Available sample format is listed below: - [S8|U8|S16|U16|S32|U32][_LE|_BE] - [S24|U24][_LE|_BE] - FLOAT[_LE|_BE] - FLOAT64[_LE|_BE] - IEC958_SUBFRAME[_LE|_BE] - MU_LAW - A_LAW - [S20|U20][_LE|_BE] - [S24|U24][_3LE|_3BE] - [S20|U20][_3LE|_3BE] - [S18|U18][_3LE|_3BE] - DSD_U8 - DSD_[U16|U32][_LE|_BE] If endian\-ness is omitted, host endian\-ness is used. Some special formats are available: - cd (16 bit little endian, 44100, stereo) [= \-f S16_LE \-c 2 \-r 44100] - cdr (16 bit big endian, 44100, stereo) [= \-f S16_BE \-c 2 \-f 44100] - dat (16 bit little endian, 48000, stereo) [= \-f S16_LE \-c 2 \-r 48000] If omitted, .I U8 is used as a default. Actual available formats are restricted by each transmission backend. Unavailable sample format is listed below. These format has size of data frame unaligned to byte unit. - IMA_ADPCM - MPEG - GSM - SPECIAL - G723_24 - G723_24_1B - G723_40 - G723_40_1B .TP .B \-c, \-\-channels=# 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 256 \&. If omitted, .I 1 is used as a default. .TP .B \-r, \-\-rate=# 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 , it\(aqs interpreted by .I kHz unit. The value should be between .I 2000 and .I 192000 \&. If omitted, .I 8000 is used as a default. .TP .B \-t, \-\-file\-type=TYPES Indicate the type of file. This is required for capture transmission. Available types are listed below: - wav: Microsoft/IBM RIFF/Wave format - au, sparc: Sparc AU format - voc: Creative Tech. voice format - raw: raw data When nothing is indicated, for capture transmission, the type is decided according to suffix of .I filepath , and .I raw type is used for fallback. .TP .B \-I, \-\-separate\-channels Indicate this option when several files are going to be handled. For capture transmission, if one filepath is given as .I filepath , a list of .I filepaths is generated in a formula \(aq\-[.suffix]\(aq. The suffix is omitted when raw format of container is used. .TP .B \-\-dump\-hw\-params Dump hardware parameters and finish run time if backend supports it. .TP .B \-\-xfer\-backend=BACKEND Select backend of transmission from a list below. The default is libasound. .br - libasound - libffado (optional if compiled) .SS Backend options for libasound (placeholder) .SS Backend options for libffado (placeholder) .SH POSIX SIGNALS During transmission, .I SIGINT and .I SIGTERM The above will close handled files and finish run time. .I SIGTSTP The above will suspend PCM substream and .I SIGCONT The above will resume it. No XRUNs are expected. The other signals perform default behaviours. .SH EXAMPLES .PP .in +4n .EX .B $ axfer transfer playback \-d 1 something .EE .in .PP The above will transfer audio data frame in \(aqsomething\(aq file for playback during 1 second. The sample format is detected automatically as a result to parse \(aqsomething\(aq as long as it\(aqs compliant to one of Microsoft/IBM RIFF/Wave, Sparc AU, Creative Tech. voice formats. If nothing detected, .I \-r , .I \-c and .I \-f should be given, or .I \-f should be given with special format. .PP .in +4n .EX .B $ axfer transfer playback \-r 22050 \-c 1 \-f S16_LE \-t raw something .EE .in .PP The above will transfer audio data frame in \(aqsomething\(aq 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 from keyboard or .I SIGTERM by .I kill(1) \&. .PP .in +4n .EX .B $ axfer transfer capture \-d 10 \-f cd something.wav .EE .in .PP The above will transfer audio data frame to \(aqsomething.wav\(aq 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 \&. .PP .in +4n .EX .B $ axfer transfer capture \-s 1024 \-r 48000 \-c 2 \-f S32_BE \-I \-t au channels .EE .in .PP 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 \(aqchannels\-1.au\(aq and \(aqchannels\-2.au\(aq. .SH COMPATIBILITY TO APLAY The .B transfer subcommand of .B axfer is designed to keep compatibility to aplay(1). However some options below are not compatible due to several technical reasons. .TP .I \-I, \-\-separate\-channels This option is supported just for files to store audio data frames corresponding to each channel. In aplay(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. .TP .I \-\-max\-file\-time=# This option is unsupported. In aplay(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. .TP .I \-\-use\-strftime=FORMAT This option is unsupported. In aplay(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 strftime(3). However, this option requires extra string processing for file paths and it\(aqs bothersome if written in C language. .TP .I \-\-process\-id\-file=FILEPATH This option is unsupported. In aplay(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. .TP .I \-V, \-\-vumeter=TYPE This option is not supported at present. In aplay(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. .TP .I \-i, \-\-interactive This option is not supported at present. In aplay(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. .TP .I SIGTSTP, SIGCONT This performs suspend/resume of PCM substream. In aplay(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. .TP .I SIGUSR1 This is not supported. In aplay(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 option, this option should increase complexity of main loop of axfer. .SH DESIGN .SS Modular structure This program consists of three modules; .I xfer , .I mapper and .I container \&. Each module has an abstraction layer to enable actual implementation. .nf -------- ---------- ------------- device <-> | xfer | <-> | mapper | <-> | container | <-> file -------- ---------- ------------- libasound single wav libffado multiple au voc raw .fi The .I xfer module performs actual transmission to devices and nodes. The module can have several transmission backends. As a default backend, .I libasound backend is used to perform transmission via alsa\-lib APIs. The module allows each backend to parse own command line options. The .I container 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 ), Sparc AU ( .I au ) and Creative Technology voice ( .I voc ). Additionally, a special container is prepared for raw audio data ( .I raw ). The .I mapper module handles buffer layout and alignment for transmission of audio data frame. The module has two implementations; .I single and .I multiple \&. The .I single backend uses one container to construct the buffer. The .I multiple backend uses several containers to construct it. .SS Care of copying audio data frame Between the .I xfer module and .I mapper 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 module and .I container module, a pointer to one buffer is passed because supported media containers including raw type store audio data frames in interleaved order. 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. - xfer(mmap/interleaved), mapper(single), container(any) - xfer(mmap/non\-interleaved), mapper(multiple), containers(any) .SH SEE ALSO \fB axfer(1), axfer\-list(1), alsamixer(1), amixer(1) \fP .SH AUTHOR Takashi Sakamoto