1AXFER-TRANSFER(1)           General Commands Manual          AXFER-TRANSFER(1)
2
3
4

NAME

6       axfer-transfer  - transferrer of audio data frame for sound devices and
7       nodes.
8
9

SYNOPSIS

11       axfer transfer direction [  common-options  ]  [  backend-options  ]  [
12       filepath ]
13
14       axfer  transfer  direction  [ common-options ] [ backend-options ] -I |
15       --separate-channels filepath ...
16
17       direction = capture | playback
18
19       common-options = ( read OPTIONS section )
20
21       backend-options = ( read OPTIONS section )
22
23       filepaths = ( read OPTIONS section )
24
25

DESCRIPTION

27       The transfer subcommand of axfer performs transmission  of  audio  data
28       frames  for  devices  available  in supported backends. This program is
29       essentially designed to use alsa-lib APIs (libasound backend) to handle
30       sound devices supported by Linux sound subsystem (ALSA).
31
32

OPTIONS

34   Direction
35       capture
36              Operates for capture transmission.
37
38
39       playback
40              Operates for playback transmission.
41
42
43   Filepath
44       Filepath  is handled as a path relative to current working directory of
45       run time if it's not full path from root directory.
46
47       The standard input or output is used if filepath is  not  specified  or
48       given as '-' .
49
50       For  playback  transmission,  container  format  of  given  filepath is
51       detected automatically and metadata is used for  parameters  of  sample
52       format, channels, rate, duration. If nothing detected, content of given
53       file path is handled as raw data. In this case, the  parameters  should
54       be indicated as options.
55
56       Multiple filepaths are allowed with -I | --separate-channels option. In
57       this case, standard  input  and  output  is  not  available.  The  same
58       filepath is not allowed except for paths listed below:
59        - /dev/null
60        - /dev/zero
61        - /dev/full
62        - /dev/random
63        - /dev/urandom
64
65
66   Common options
67       -h, --help
68              Print help messages and finish run time.
69
70
71       -q, --quiet
72              Quiet mode. Suppress messages (not sound :))
73
74
75       -v, --verbose
76              Verbose  mode.  Runtime dumps supplemental information according
77              to the number of this option given in command line.
78
79
80       -d, --duration=#
81              Interrupt after # seconds. A value of zero means  infinity.  The
82              default is zero, so if this option is omitted then the transmis‐
83              sion process will run until it is killed. Either -d or -s option
84              is available exclusively.
85
86
87       -s, --samples=#
88              Interrupt after transmission of # number of data frames. A value
89              of zero means infinity. The default is zero, so if this  options
90              is  omitted  then  the transmission process will run until it is
91              killed. Either -d or -s option is available exclusively.
92
93
94       -f, --format=FORMAT
95              Indicate format of audio sample. This is  required  for  capture
96              transmission,  or playback transmission with files including raw
97              audio data.
98
99              Available sample format is listed below:
100               - [S8|U8|S16|U16|S32|U32][_LE|_BE]
101               - [S24|U24][_LE|_BE]
102               - FLOAT[_LE|_BE]
103               - FLOAT64[_LE|_BE]
104               - IEC958_SUBFRAME[_LE|_BE]
105               - MU_LAW
106               - A_LAW
107               - [S20|U20][_LE|_BE]
108               - [S24|U24][_3LE|_3BE]
109               - [S20|U20][_3LE|_3BE]
110               - [S18|U18][_3LE|_3BE]
111               - DSD_U8
112               - DSD_[U16|U32][_LE|_BE]
113
114              If endian-ness is omitted, host endian-ness is used.
115
116              Some special formats are available:
117               - cd (16 bit little endian, 44100, stereo) [= -f S16_LE -c 2 -r
118              44100]
119               -  cdr  (16 bit big endian, 44100, stereo) [= -f S16_BE -c 2 -f
120              44100]
121               - dat (16 bit little endian, 48000, stereo) [= -f S16_LE  -c  2
122              -r 48000]
123
124              If  omitted,  U8  is used as a default. Actual available formats
125              are restricted by each transmission backend.
126
127              Unavailable sample format is listed below. These format has size
128              of data frame unaligned to byte unit.
129
130               - IMA_ADPCM
131               - MPEG
132               - GSM
133               - SPECIAL
134               - G723_24
135               - G723_24_1B
136               - G723_40
137               - G723_40_1B
138
139
140       -c, --channels=#
141              Indicate  the  number  of  audio data samples per frame. This is
142              required for capture transmission, or playback transmission with
143              files including raw audio data. The value should be between 1 to
144              256 . If omitted, 1 is used as a default.
145
146
147       -r, --rate=#
148              Indicate the number of audio data  frame  per  second.  This  is
149              required for capture transmission, or playback transmission with
150              files including raw audio data. If the value is less than 1000 ,
151              it's  interpreted  by kHz unit. The value should be between 2000
152              and 192000 . If omitted, 8000 is used as a default.
153
154
155       -t, --file-type=TYPE
156              Indicate the type of file. This is required for  capture  trans‐
157              mission. Available types are listed below:
158               - wav: Microsoft/IBM RIFF/Wave format
159               - au, sparc: Sparc AU format
160               - voc: Creative Tech. voice format
161               - raw: raw data
162
163              When nothing is indicated, for capture transmission, the type is
164              decided according to suffix of filepath , and raw type  is  used
165              for fallback.
166
167
168       -I, --separate-channels
169              Indicate this option when several files are going to be handled.
170              For capture transmission, if one filepath is given as filepath ,
171              a    list    of    filepaths   is   generated   in   a   formula
172              '<filepath>-<sequential number>[.suffix]'.  The suffix is  omit‐
173              ted when raw format of container is used.
174
175
176       --dump-hw-params
177              Dump hardware parameters and finish run time if backend supports
178              it.
179
180
181       --xfer-backend=BACKEND
182              Select backend of transmission from a list below. The default is
183              libasound.
184               - libasound
185               - libffado (optional if compiled)
186
187
188   Backend options for libasound
189       -D, --device=NODE
190
191              This  option  is used to select PCM node in libasound configura‐
192              tion space.  Available nodes are listed by pcm operation of list
193              subcommand.
194
195
196       -N, --nonblock
197
198              With  this option, PCM substream is opened in non-blocking mode.
199              When audio data frame is not available in buffer of the PCM sub‐
200              stream,  I/O  operation  immediately  returns  without  blocking
201              process. This option implicitly  uses  --waiter-type  option  as
202              well to prevent heavy consumption of CPU time.
203
204
205       -M, --mmap
206
207              With this option, audio data frame is processed directly in buf‐
208              fer of PCM substream if selected node supports  this  operation.
209              Without  the  option,  temporary  buffers are used to copy audio
210              data frame for buffer of PCM substream.  This option  implicitly
211              uses  --waiter-type  option as well to prevent heavy consumption
212              of CPU time.
213
214
215       -F, --period-size=#
216
217              This option  configures  given  value  to  period_size  hardware
218              parameter  of  PCM substream. The parameter indicates the number
219              of audio data frame per period in buffer of the  PCM  substream.
220              Actual number is decided as a result of interaction between each
221              implementation of PCM plugin chained from the selected PCM node,
222              and in-kernel driver or PCM I/O plugins.
223
224              Ideally, the same amount of audio data frame as the value should
225              be handled in one I/O operation. Actually, it is not,  depending
226              on  implementation of the PCM plugins, in-kernel driver, PCM I/O
227              plugins and scheduling model.  For  'hw'  PCM  plugin  in  'irq'
228              scheduling model, the value is used to decide intervals of hard‐
229              ware interrupt, thus the same amount of audio data frame as  the
230              value is expected to be available for one I/O operation.
231
232
233       --period-time=#
234
235              This  option  configures  given  value  to  period_time hardware
236              parameter  of  PCM  substream.  This  option   is   similar   to
237              --period-size option, however its unit is micro-second.
238
239
240       -B, --buffer-size=#
241
242              This  option  configures  given  value  to  buffer_size hardware
243              parameter of PCM substream. The parameter indicates  the  number
244              of audio data frame in buffer of PCM substream. Actual number is
245              decided as a result of interaction between  each  implementation
246              of  PCM plugin chained from the selected PCM node, and in-kernel
247              driver or PCM I/O plugins.
248
249              Ideally, this is multiples of the number of audio data frame per
250              period,  thus the size of period. Actually, it is not, depending
251              on implementation of the PCM plugins, in-kernel driver  and  PCM
252              I/O plugins.
253
254
255       --buffer-time=#
256
257              This  option  configures  given  value  to  buffer_time hardware
258              parameter of PCM substream. This option  is  similar  to  --buf‐
259              fer-size option, however its unit is micro-second.
260
261
262       --waiter-type=TYPE
263
264              This option indicates the type of waiter for event notification.
265              At present, four types are available; default ,  select  ,  poll
266              and  epoll  .  With default type, 'snd_pcm_wait()' is used. With
267              select type, 'select(2)' system call is used.  With  poll  type,
268              'poll(2)'  system  call is used. With epoll type, Linux-specific
269              'epoll(7)' system call is used.
270
271              This option should correspond to one  of  --nonblock  or  --mmap
272              options,  or  timer value of --sched-model option.  Neither this
273              option nor --test-nowait is available at the same time.
274
275
276       --sched-model=MODEL
277
278              This option selects scheduling model for process  of  this  pro‐
279              gram.  One  of irq or timer is available. In detail, please read
280              'SCHEDULING MODEL' section.
281
282              When nothing specified, irq model is used.
283
284
285       -A, --avail-min=#
286
287              This option configures given value to avail-min software parame‐
288              ter  of  PCM  substream.  In blocking mode, the value is used as
289              threshold of the number of available audio data frames in buffer
290              of PCM substream to wake up process blocked by I/O operation. In
291              non-blocking mode, any I/O operation returns -EAGAIN untill  the
292              available number of audio data frame reaches the threshold.
293
294              This  option  has  an  effect  in cases neither --mmap nor timer
295              value of --sched-model option is used.
296
297
298       -R, --start-delay=#
299
300              This option configures given value to  start_threshold  software
301              parameter  of  PCM  substream. The value is used as threshold to
302              start PCM substream automatically. At present, this  option  has
303              an   effect   in   cases  neither  --mmap  nor  timer  value  of
304              --sched-model option is used.
305
306              For playback transmission, when the number of accumulated  audio
307              data  frame  in  buffer  of  PCM substream to which this program
308              writes out reaches the threshold, the PCM substream starts auto‐
309              matically without an explicit call of snd_pcm_start() to the PCM
310              substream.
311
312              For capture transmission, this option is useless. The number  of
313              accumulated  audio  data  frame  is  not  increased  without  an
314              explicit call of snd_pcm_start() to the PCM substream.
315
316              This option has an effect in  cases  neither  --mmap  nor  timer
317              value of --sched-model option is used.
318
319
320       -T, --stop-delay=#
321
322              This  option  configures  given value to stop_threshold software
323              parameter of PCM substream. The value is used  as  threshold  to
324              stop PCM substream automatically. At present, this option has an
325              effect in cases neither --mmap nor timer value of  --sched-model
326              option is used.
327
328              For  capture  transmission, when the number of accumulated audio
329              data frame in buffer of PCM  substream  to  which  a  driver  or
330              alsa-lib  PCM  plugins write reaches the threshold, the PCM sub‐
331              stream  stops  automatically  without  an   explicit   call   of
332              snd_pcm_stop()  to  the  PCM substream. This is a case that this
333              program leaves the audio  data  frames  without  reading  for  a
334              while.
335
336              For  playback transmission, when the number available audio data
337              frame in buffer of PCM substream from which a driver or alsa-lib
338              PCM  plugins read reaches the threshold, the PCM substream stops
339              automatically without an explicit call of snd_pcm_stop() to  the
340              PCM substream. This is a case that this program leaves the audio
341              data frames without writing for a while.
342
343              This option has an effect in  cases  neither  --mmap  nor  timer
344              value of --sched-model option is used.
345
346
347       --disable-resample
348
349              This  option has an effect for 'plug' plugin in alsa-lib to sup‐
350              press conversion of sampling rate for audio data frame.
351
352
353       --disable-channels
354
355              This option has an effect for 'plug' plugin in alsa-lib to  sup‐
356              press conversion of channels for audio data frame.
357
358
359       --disable-format
360
361              This  option has an effect for 'plug' plugin in alsa-lib to sup‐
362              press conversion of sample format for audio data frame.
363
364
365       --disable-softvol
366
367              This option has an effect for 'softvol' plugin  in  alsa-lib  to
368              suppress  conversion  of  samples for audio data frame via addi‐
369              tional control element.
370
371
372       --fatal-errors
373
374              This option suppresses recovery operation  from  XRUN  state  of
375              running  PCM substream, then process of this program is going to
376              finish as usual.
377
378
379       --test-nowait
380
381              This option disables any waiter for I/O event notification.  I/O
382              operations  are  iterated till any of audio data frame is avail‐
383              able. The option brings heavy load in consumption of CPU time.
384
385
386   Backend options for libffado
387       This backend is automatically available when configure  script  detects
388       ffado_streaming_init() symbol in libffado shared object.
389
390
391       -p, --port=#
392
393              This  option  uses  given  value  to decide which 1394 OHCI con‐
394              troller is used to communicate. When Linux system has  two  1394
395              OHCI  controllers, 0 or 1 are available. Neither this option nor
396              -g is available at the same time. If nothing specified, libffado
397              performs to communicate to units on IEEE 1394 bus managed by all
398              of 1394 OHCI controller available in Linux system.
399
400
401       -n, --node=#
402
403              This option uses given value to decide which  unit  is  used  to
404              communicate.  This  option  requires -p option to indicate which
405              1394 OHCI controller is used to  communicate  to  the  specified
406              unit.
407
408
409       -g, --guid=HEXADECIMAL
410
411              This option uses given value to decide a target unit to communi‐
412              cate. The value should be prefixed with  '0x'  and  consists  of
413              hexadecimal literal letters (0-9, a-f, A-F). Neither this option
414              nor -p is available at the  same  time.  If  nothing  specified,
415              libffado  performs to communicate to units on IEEE 1394 bus man‐
416              aged by all of 1394 OHCI controller available in Linux system.
417
418
419       --frames-per-period=#
420
421              This option uses given value to decide the number of audio  data
422              frame in one read/write operation. The operation is blocked till
423              the number of available  audio  data  frame  exceeds  the  given
424              value. As a default, 512 audio data frames is used.
425
426
427       --periods-per-buffer=#
428
429              This  option uses given value to decide the size of intermediate
430              buffer between this program and libffado. As a default, 2  peri‐
431              ods per buffer is used.
432
433
434       --slave
435
436              This option allows this program to run slave mode. In this mode,
437              libffado adds unit directory into configuration ROM of 1394 OHCI
438              controller  where  Linux  system runs. The unit directory can be
439              found by the other node on the same bus.  Linux  system  running
440              on  the  node  can  transfer  isochronous packet with audio data
441              frame to the unit. This  program  can  receive  the  packet  and
442              demultiplex the audio data frame.
443
444
445       --snoop
446
447              This option allows this program to run snoop mode. In this mode,
448              libffado listens isochronous channels to which device  transfers
449              isochronous packet. When isochronous communication starts by any
450              unit on the same bus, the packets can be handled  by  this  pro‐
451              gram.
452
453
454       --sched-priority=#
455
456              This  option  executes  pthread_setschedparam()  in  a  call  of
457              ffado_streaming_init() to configure scheduling policy and  given
458              value  as its priority for threads related to isochronous commu‐
459              nication.  The given value should be within RLIMIT_RTPRIO param‐
460              eter of process. Please read getrlimit(2) for details.
461
462

POSIX SIGNALS

464       During  transmission,  SIGINT  and SIGTERM will close handled files and
465       PCM substream to be going to finish run time.
466
467       SIGTSTP will suspend PCM substream and SIGCONT will resume it. No XRUNs
468       are  expected.  With  libffado  backend, the suspend/resume is not sup‐
469       ported and runtime is aboeted immediately.
470
471       The other signals perform default behaviours.
472
473

EXAMPLES

475           $ axfer transfer playback -d 1 something
476
477       The above will transfer audio data frame in 'something' file for  play‐
478       back during 1 second.  The sample format is detected automatically as a
479       result to parse 'something' as long as it's compliant to one of  Micro‐
480       soft/IBM  RIFF/Wave, Sparc AU, Creative Tech. voice formats. If nothing
481       detected, -r , -c and -f should be given, or -f should  be  given  with
482       special format.
483
484
485           $ axfer transfer playback -r 22050 -c 1 -f S16_LE -t raw something
486
487       The  above will transfer audio data frame in 'something' file including
488       no information of sample format, as sample format of 22050  Hz,  monau‐
489       ral,  signed  16  bit  little endian PCM for playback. The transmission
490       continues till catching SIGINT from keyboard or SIGTERM by kill(1) .
491
492
493           $ axfer transfer capture -d 10 -f cd something.wav
494
495       The above will transfer audio data frame  to  'something.wav'  file  as
496       sample format of 44.1 kHz, 2 channels, signed 16 bit little endian PCM,
497       during 10 seconds. The file format is Microsoft/IBM RIFF/Wave according
498       to suffix of the given filepath .
499
500
501           $ axfer transfer capture -s 1024 -r 48000 -c 2 -f S32_BE -I -t au channels
502
503       The  above will transfer audio data frame as sample format of 48.0 kHz,
504       2 channels, signed 32 bit big endian  PCM  for  1,024  number  of  data
505       frames to files named 'channels-1.au' and 'channels-2.au'.
506
507

SCHEDULING MODEL

509       In  a  design  of  ALSA PCM core, runtime of PCM substream supports two
510       modes; period-wakeup and no-period-wakeup.  These  two  modes  are  for
511       different scheduling models.
512
513
514   IRQ-based scheduling model
515       As a default, period-wakeup mode is used. In this mode, in-kernel driv‐
516       ers should operate hardware to  generate  periodical  notification  for
517       transmission  of  audio  data  frame.  The  interval of notification is
518       equivalent to the same amount of audio data frame as one period of buf‐
519       fer, against actual time.
520
521       In  a  handler  assigned to the notification, a helper function of ALSA
522       PCM core is called to update a position to head of  hardware  transmis‐
523       sion,  then compare it with a position to head of application operation
524       to judge overrun/underrun (XRUN) and to wake up blocked processes.
525
526       For this purpose, hardware IRQ of controller for serial audio bus  such
527       as  Inter-IC sound is typically used. In this case, the controller gen‐
528       erates the IRQ according to transmission on the serial  audio  bus.  In
529       the handler assigned to the IRQ, direct media access (DMA) transmission
530       is requested between dedicated host memory and device memory.
531
532       If target hardware doesn't support this kind of mechanism, the periodi‐
533       cal  notification should be emulated by any timer; e.g. hrtimer, kernel
534       timer.  External PCM plugins generated by PCM plugin  SDK  in  alsa-lib
535       should also emulate the above behaviour.
536
537       In  this mode, PCM applications are programmed according to typical way
538       of I/O operations. They execute blocking  system  calls  to  read/write
539       audio  data  frame in buffer of PCM substream, or blocking system calls
540       to wait until any audio data frame is available. In  axfer  ,  this  is
541       called  IRQ-based  scheduling  model and a default behaviour. Users can
542       explicitly configure this mode by usage of  --sched-model  option  with
543       irq value.
544
545
546   Timer-based scheduling model
547       The  no-period-wakeup  mode  is an optional mode of runtime of PCM sub‐
548       stream. The mode assumes a specific feature of hardware and  assist  of
549       in-kernel  driver and PCM applications. In this mode, in-kernel drivers
550       don't operate hardware to generate periodical notification  for  trans‐
551       mission  of  audio  data frame.  The hardware should automatically con‐
552       tinue transmission of audio data frame without periodical operation  of
553       the drivers; e.g. according to auto-triggered DMA transmission, a chain
554       of registered descriptors.
555
556       In this mode, nothing wakes up blocked processes, therefore PCM  appli‐
557       cations  should  be programmed without any blocking operation. For this
558       reason, this mode is enabled when the PCM applications explicitly  con‐
559       figure  hardware parameter to runtime of PCM substream, to prevent dis‐
560       order of existing applications.  Additionally, nothing maintains timing
561       for  transmission  of  audio data frame, therefore the PCM applications
562       should voluntarily handle any timer to queue audio data frame in buffer
563       of the PCM substream for lapse of time. Furthermore, instead of driver,
564       the PCM application should call a helper function of ALSA PCM  core  to
565       update a position to head of hardware transmission and to check XRUN.
566
567       In axfer , this is called timer-based scheduling model and available as
568       long as hardware/driver assists no-period-wakeup runtime. Users  should
569       explicitly  set  this  mode by usage of --sched-model option with timer
570       value.
571
572       In the scheduling model, PCM applications need  to  care  of  available
573       space  on  PCM  buffer  by lapse of time, typically by yielding CPU and
574       wait for rescheduling. For the  yielding,  timeout  is  calculated  for
575       preferable  amount  of  PCM  frames to process. This is convenient to a
576       kind of applications, like sound servers. when an  I/O  thread  of  the
577       server  wait  for the timeout, the other threads can process audio data
578       frames for server clients. Furthermore, with  usage  of  rewinding/for‐
579       warding,  applications  can  achieve  low  latency between transmission
580       position and handling position even if they uses large size of PCM buf‐
581       fers.
582
583
584   Advantages and issues
585       Ideally,   timer-based   scheduling  model  has  some  advantages  than
586       IRQ-based scheduling model. At first, no interrupt context runs for PCM
587       substream. The PCM substream is handled in any process context only. No
588       need to care of race conditions between IRQ and process contexts.  This
589       reduces  some concerns for some developers of drivers and applications.
590       Secondary, CPU time is not used for handlers on the interrupt  context.
591       The  CPU  time  can be dedicated for the other tasks. This is good in a
592       point of Time Sharing System. Thirdly, hardware is  not  configured  to
593       generate  interrupts.  This  is good in a point of reduction of overall
594       power consumption possibly.
595
596       In either scheduling model, the hardware should allow drivers  to  read
597       the number of audio data frame transferred between the dedicated memory
598       and the device memory for audio serial  bus.  However,  in  timer-based
599       scheduling  model, fine granularity and accuracy of the value is impor‐
600       tant. Actually hardware performs transmission between dedicated  memory
601       and device memory for a small batch of audio data frames or bytes. In a
602       view of PCM applications, the granularity in  current  transmission  is
603       required  to decide correct timeout for each I/O operation. As of Linux
604       kernel v4.21, ALSA PCM interface between kernel/userspace has  no  fea‐
605       ture to report it.
606
607

COMPATIBILITY TO APLAY

609       The  transfer  subcommand of axfer is designed to keep compatibility to
610       aplay(1). However some options below are not compatible due to  several
611       technical reasons.
612
613
614       -I, --separate-channels
615              This  option  is  supported  just  for files to store audio data
616              frames corresponding to each channel.  In  aplay(1)  implementa‐
617              tion,  this  option  has  an additional effect to use PCM buffer
618              aligned to non-interleaved order if a target device supports. As
619              of  2018,  PCM buffer of non-interleaved order is hardly used by
620              sound devices.
621
622
623       -A, --avail-min=#
624              This option indicates threshold to wake up blocked process in  a
625              unit  of audio data frame. Against aplay(1) implementation, this
626              option has no effect with --mmap option  as  well  as  timer  of
627              --sched-model option.
628
629
630       -R, --start-delay=#
631              This  option indicates threshold to start prepared PCM substream
632              in a unit of audio data frame. Against aplay(1)  implementation,
633              this option has no effect with --mmap option as well as timer of
634              --sched-model option.
635
636
637       -T, --stop-delay=#
638              This option indicates threshold to stop running PCM substream in
639              a  unit  of  audio  data frame. Against aplay(1) implementation,
640              this option has no effect with --mmap option as well as timer of
641              --sched-model option.
642
643
644       --max-file-time=#
645              This  option  is  unsupported.  In  aplay(1) implementation, the
646              option has an effect for capture transmission to save  files  up
647              to  the  same number of data frames as the given value by second
648              unit, or the maximum number of data  frames  supported  by  used
649              file  format.  When  reaching  to  the  limitation, used file is
650              closed, then new file is opened and audio data frames are  writ‐
651              ten.  However,  this option requires extra handling of files and
652              shall increase complexity of main loop of axfer.
653
654
655       --use-strftime=FORMAT
656              This option is  unsupported.  In  aplay(1)  implementation,  the
657              option  has  an effect for capture transmission to generate file
658              paths according to given format in which some extra formats  are
659              available  as well as formats supported by strftime(3). However,
660              this option requires extra string processing for file paths  and
661              it's bothersome if written in C language.
662
663
664       --process-id-file=FILEPATH
665              This  option  is  unsupported.  In  aplay(1) implementation, the
666              option has an effect to create a file for given value and  write
667              out  process  ID to it. This file allows users to get process ID
668              and send any POSIX signal to aplay process.  However, this  idea
669              has some troubles for file locking when multiple aplay processes
670              run with the same file.
671
672
673       -V, --vumeter=TYPE
674              This option is not supported at present. In aplay(1) implementa‐
675              tion,  this option has an effect to occupy stdout with some ter‐
676              minal control characters and display vumeter  for  monaural  and
677              stereo  channels.  However,  some  problems lay; this feature is
678              just for audio data frames with PCM format, this feature  brings
679              disorder of terminal after aborting, stdout is not available for
680              pipeline.
681
682
683       -i, --interactive
684              This option is not supported at present. In aplay(1) implementa‐
685              tion,  this  option  has an effect to occupy stdin for key input
686              and suspend/resume PCM substream according to pushed enter  key.
687              However,  this  feature requires an additional input handling in
688              main loop and leave bothersome operation to  maintain  PCM  sub‐
689              stream.
690
691
692       -m, --chmap=CH1,CH2,...
693              ALSA  PCM  core  and  control core doesn't support this feature,
694              therefore remapping should be done  in  userspace.  This  brings
695              overhead  to align audio data frames, especially for mmap opera‐
696              tion. Furthermore, as of alsa-lib  v1.1.8,  some  plugins  don't
697              support  this  feature expectedly, thus this option is a lack of
698              transparent operation. At present, this option is not  supported
699              yet not to confuse users.
700
701
702       SIGTSTP, SIGCONT
703              This  performs  suspend/resume  of  PCM  substream.  In aplay(1)
704              implementation, these operations bring XRUN state  to  the  sub‐
705              stream,  and  suspend/resume  is done in interactive mode in the
706              above. Some developers use the signal  for  recovery  test  from
707              XRUN. At present, no alternative is supported for the test.
708
709
710       SIGUSR1
711              This  is  not supported. In aplay(1) implementation, this signal
712              is assigned to a handler to close a current file to store  audio
713              data  frame and open a new file to continue processing. However,
714              as well as --max-file-time option, this option  should  increase
715              complexity of main loop of axfer.
716
717

DESIGN

719   Modular structure
720       This  program  consists of three modules; xfer , mapper and container .
721       Each module has an abstraction layer to enable actual implementation.
722
723                  --------     ----------     -------------
724       device <-> | xfer | <-> | mapper | <-> | container | <-> file
725                  --------     ----------     -------------
726                   libasound    single         wav
727                   libffado     multiple       au
728                                               voc
729                                               raw
730
731       The xfer module performs actual transmission to devices and nodes.  The
732       module  can  have  several transmission backends. As a default backend,
733       libasound backend is used to perform transmission  via  alsa-lib  APIs.
734       The module allows each backend to parse own command line options.
735
736       The  container  module  performs  to  read/write  audio  data frame via
737       descriptor for file/stream of multimedia container  or  raw  data.  The
738       module  automatically  detect  type  of  multimedia container and parse
739       parameters in its metadata of data header. At present, three  types  of
740       multimedia  containers  are supported; Microsoft/IBM RIFF/Wave ( wav ),
741       Sparc AU ( au ) and Creative Technology voice ( voc ). Additionally,  a
742       special container is prepared for raw audio data ( raw ).
743
744       The  mapper module handles buffer layout and alignment for transmission
745       of audio data frame.  The module has two  implementations;  single  and
746       multiple .  The single backend uses one container to construct the buf‐
747       fer. The multiple backend uses several containers to construct it.
748
749
750   Care of copying audio data frame
751       Between the xfer module and mapper module, a pointer to buffer  includ‐
752       ing  audio data frames is passed. This buffer has two shapes for inter‐
753       leaved and non-interleaved order. For the former, the pointer points to
754       one  buffer.  For  the  latter, the pointer points to an array in which
755       each element points to one buffer. Between the mapper module  and  con‐
756       tainer  module,  a  pointer  to  one buffer is passed because supported
757       media containers including raw type store audio data frames  in  inter‐
758       leaved order.
759
760       In passing audio data frame between the modules, axfer is programmed to
761       avoid copying between a buffer to another buffer as much  as  possible.
762       For  example,  in  some scenarios below, no copying occurs between mod‐
763       ules.
764
765        - xfer(mmap/interleaved), mapper(single), container(any)
766        - xfer(mmap/non-interleaved), mapper(multiple), containers(any)
767
768
769   Unit test
770       For each of the mapper and container module, unit test is available. To
771       run the tests, execute below command:
772
773       $ make test
774
775       Each  test  iterates  writing  to file and reading to the file for many
776       times and it takes long time to finish. Please take care of the  execu‐
777       tion time if running on any CI environment.
778
779

SEE ALSO

781        axfer(1), axfer-list(1), alsamixer(1), amixer(1)
782
783

AUTHOR

785       Takashi Sakamoto <o-takashi@sakamocchi.jp>
786
787
788
789alsa-utils                     28 November 2018              AXFER-TRANSFER(1)
Impressum