[wip] [api] [cli] roc-streaminggh-608: Formats and sub-formats

API
---

  TODO

CLI
---

  1. --io-encoding option now has form
    <format>@<subformat>/<rate>/<channels>

  E.g.: pcm@s16/44100/stereo
  (whether sub-format is allowed or required depends
   on format)

  2. --input-format/--output-format options are removed,
     their function is now handled by <format> field
     of --io-encoding

  E.g.:
    --output file://- --io-encoding wav@s24/48000/stereo
     or
    --input file://- --io-encoding wav/-/-

  3. --print-supported is updated to discover and list all
     available sub-formats (divided into logical groups).

Docs
----

  TODO

Internals
---------

Introduce concept of format (e.g. PCM, FLAC) and sub-format
(e.g. s16). Support formats and sub-formats in all sndio
backends.

roc_audio:

- SampleFormat => Format
- Formats: Format_Pcm, Format_Wav, Format_Custom
- PcmFormat => PcmSubformat
- SampleSpec: set_format(), set_custom_format(),
  set_pcm_subformat(), set_custom_subformat()
- SampleSpec: is_valid() => is_complete()
- Sample_RawFormat => PcmSubformat_Raw

roc_sndio:

- File formats are now *not* drivers. All file formats
  are handles by special "file://" driver, i.e.
  URI scheme is now always equal to driver.
- Supported file formats and sub-formats are
  discovered from backends separately from drivers.
- For discovery, we use DriverInfo and FormatInfo
  structs.

- IoConfig is empty by default; frame length and latency
  are zero.
- Each backend may use its own defaults for IoConfig.
- We can retrieve actually selected config using
  sample_spec() and frame_length() methods of IDevice.

- SoxBackend: remove file support, allow only devices
  (now we use sndfile for files)
- SoxBackend: support PCM format and sub-formats
- PulseaudioBackend: support PCM format and sub-formats
- SndfileBackend: support formats and sub-formats,
  map to sndfile major type and sub-type
- WavBackend: support WAV format and PCM sub-formats

- Unification of sndio backends
- Bug-fixes in format handling in sndfile backend

.fmtignore

@@ -1,5 +1,5 @@
 src/internal_modules/roc_audio/channel_tables.cpp
-src/internal_modules/roc_audio/pcm_format.cpp
+src/internal_modules/roc_audio/pcm_subformat.cpp
 src/internal_modules/roc_core/macro_helpers.h
 src/internal_modules/roc_core/target_libatomic_ops/roc_core/atomic_ops.h
 src/public_api/include/roc/version.h

SConstruct

@@ -729,10 +729,10 @@ env['ROC_MODULES'] = [
     'roc_audio',
     'roc_rtp',
     'roc_rtcp',
+    'roc_sdp',
     'roc_netio',
     'roc_sndio',
     'roc_pipeline',
-    'roc_sdp',
     'roc_ctl',
     'roc_node',
 ]

docs/man/roc-copy.1

@@ -60,15 +60,12 @@ List supported protocols, formats, etc.
 .BI \-i\fP,\fB  \-\-input\fB= FILE_URI
 Input file URI
 .TP
-.BI \-\-input\-format\fB= FILE_FORMAT
-Force input file format
+.BI \-\-input\-encoding\fB= IO_ENCODING
+Input file encoding
 .TP
 .BI \-o\fP,\fB  \-\-output\fB= FILE_URI
 Output file URI
 .TP
-.BI \-\-output\-format\fB= FILE_FORMAT
-Force output file format
-.TP
 .BI \-\-output\-encoding\fB= IO_ENCODING
 Output file encoding
 .TP
@@ -150,7 +147,7 @@ Convert sample rate to 24\-bit 48k stereo:
 .sp
 .nf
 .ft C
-$ roc\-copy \-vv \-\-io\-encoding s24/48000/stereo \-i file:input.wav \-o file:output.wav
+$ roc\-copy \-vv \-\-io\-encoding pcm_s24/48000/stereo \-i file:input.wav \-o file:output.wav
 .ft P
 .fi
 .UNINDENT
@@ -162,7 +159,7 @@ Same, but drop output results instead of writing to file (useful for benchmarkin
 .sp
 .nf
 .ft C
-$ roc\-copy \-vv \-\-io\-encoding s24/48000/stereo \-i file:input.wav
+$ roc\-copy \-vv \-\-io\-encoding pcm_s24/48000/stereo \-i file:input.wav
 .ft P
 .fi
 .UNINDENT

docs/man/roc-recv.1

@@ -66,9 +66,6 @@ Exit when last connection is closed (default=off)
 .BI \-o\fP,\fB  \-\-output\fB= IO_URI
 Output file or device URI
 .TP
-.BI \-\-output\-format\fB= FILE_FORMAT
-Force output file format
-.TP
 .BI \-\-io\-encoding\fB= IO_ENCODING
 Output device encoding
 .TP
@@ -82,10 +79,7 @@ Output frame length, TIME units
 .INDENT 0.0
 .TP
 .BI \-\-backup\fB= IO_URI
-Backup file or device URI (used as input when there are no connections)
-.TP
-.BI \-\-backup\-format\fB= FILE_FORMAT
-Force backup file format
+Backup file URI (used as input when there are no connections)
 .UNINDENT
 .SS Network options
 .INDENT 0.0
@@ -239,7 +233,7 @@ This option is useful when device supports multiple encodings, or specific file
 Where:
 .INDENT 0.0
 .IP \(bu 2
-\fBformat\fP defines sample precision and binary representation, e.g. \fBs16_le\fP stands for little\-endian signed 16\-bit integers
+\fBformat\fP defines sample precision and binary representation, e.g. \fBpcm_s16_le\fP stands for little\-endian signed 16\-bit integer PCM
 .IP \(bu 2
 \fBrate\fP defines sample rate in Hertz (number of samples per second), e.g. \fB48000\fP
 .IP \(bu 2
@@ -251,11 +245,11 @@ Any component may be set to special value \fB\-\fP, which means use default valu
 Examples:
 .INDENT 0.0
 .IP \(bu 2
-\fBs16/44100/mono\fP \-\- 16\-bit native\-endian integers, 44.1KHz, 1 channel
+\fBpcm_s16/44100/mono\fP \-\- 16\-bit native\-endian integers, 44.1KHz, 1 channel
 .IP \(bu 2
-\fBf32_le/48000/stereo\fP \-\- 32\-bit little\-endian floats, 48KHz, 2 channels
+\fBpcm_f32_le/48000/stereo\fP \-\- 32\-bit little\-endian floats, 48KHz, 2 channels
 .IP \(bu 2
-\fBs24_4be/\-/\-\fP \-\- 24\-bit PCM packed into 4\-byte big\-endian frames, default rate and channels
+\fBpcm_s24_4be/\-/\-\fP \-\- 24\-bit PCM packed into 4\-byte big\-endian frames, default rate and channels
 .UNINDENT
 .sp
 The list of supported formats and channel layouts can be retrieved using \fB\-\-list\-supported\fP option.
@@ -330,7 +324,7 @@ Where:
 .IP \(bu 2
 \fBid\fP is an arbitrary number in range 100..127, which should uniquely identify encoding on all related senders and receivers
 .IP \(bu 2
-\fBformat\fP defines sample precision and binary representation, e.g. \fBs16_le\fP stands for little\-endian signed 16\-bit integers
+\fBformat\fP defines sample precision and binary representation, e.g. \fBpcm_s24\fP stands for 24\-bit signed integer PCM
 .IP \(bu 2
 \fBrate\fP defines sample rate in Hertz (number of samples per second), e.g. \fB48000\fP
 .IP \(bu 2
@@ -340,9 +334,9 @@ Where:
 Examples:
 .INDENT 0.0
 .IP \(bu 2
-\fB101:s16_be/44100/mono\fP \-\- 16\-bit big\-endian integers, 44.1KHz, 1 channel
+\fB101:pcm_s24/44100/mono\fP \-\- 24\-bit network\-endian integers, 44.1KHz, 1 channel
 .IP \(bu 2
-\fB102:f32_le/48000/stereo\fP \-\- 32\-bit little\-endian floats, 48KHz, 2 channels
+\fB102:pcm_f32/48000/stereo\fP \-\- 32\-bit network\-endian floats, 48KHz, 2 channels
 .UNINDENT
 .sp
 The list of supported formats and channel layouts can be retrieved using \fB\-\-list\-supported\fP option.
@@ -650,7 +644,7 @@ Force specific encoding on the output device:
 .nf
 .ft C
 $ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \e
-    \-\-output alsa://hw:1,0 \-\-io\-encoding s32/48000/stereo
+    \-\-output alsa://hw:1,0 \-\-io\-encoding pcm_s32/48000/stereo
 .ft P
 .fi
 .UNINDENT
@@ -662,7 +656,7 @@ Use specific encoding for network packets:
 .sp
 .nf
 .ft C
-$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-\-packet\-encoding 101:s32/48000/stereo
+$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-\-packet\-encoding 101:pcm_s24/48000/stereo
 .ft P
 .fi
 .UNINDENT
@@ -672,7 +666,7 @@ $ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-\-packet\-encoding 101:s32/48000/
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \-\-packet\-encoding 101:s32/48000/stereo
+$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \-\-packet\-encoding 101:pcm_s24/48000/stereo
 .ft P
 .fi
 .UNINDENT

docs/man/roc-send.1

@@ -60,9 +60,6 @@ List supported protocols, formats, etc.
 .BI \-i\fP,\fB  \-\-input\fB= IO_URI
 Input file or device URI
 .TP
-.BI \-\-input\-format\fB= FILE_FORMAT
-Force input file format
-.TP
 .BI \-\-io\-encoding\fB= IO_ENCODING
 Input device encoding
 .TP
@@ -223,7 +220,7 @@ This option is useful when device supports multiple encodings. Note that I/O enc
 Where:
 .INDENT 0.0
 .IP \(bu 2
-\fBformat\fP defines sample precision and binary representation, e.g. \fBs16_le\fP stands for little\-endian signed 16\-bit integers
+\fBformat\fP defines sample precision and binary representation, e.g. \fBpcm_s16_le\fP stands for little\-endian signed 16\-bit integer PCM
 .IP \(bu 2
 \fBrate\fP defines sample rate in Hertz (number of samples per second), e.g. \fB48000\fP
 .IP \(bu 2
@@ -235,11 +232,11 @@ Any component may be set to special value \fB\-\fP, which means use default valu
 Examples:
 .INDENT 0.0
 .IP \(bu 2
-\fBs16/44100/mono\fP \-\- 16\-bit native\-endian integers, 44.1KHz, 1 channel
+\fBpcm_s16/44100/mono\fP \-\- 16\-bit native\-endian integers, 44.1KHz, 1 channel
 .IP \(bu 2
-\fBf32_le/48000/stereo\fP \-\- 32\-bit little\-endian floats, 48KHz, 2 channels
+\fBpcm_f32_le/48000/stereo\fP \-\- 32\-bit little\-endian floats, 48KHz, 2 channels
 .IP \(bu 2
-\fBs24_4be/\-/\-\fP \-\- 24\-bit PCM packed into 4\-byte big\-endian frames, default rate and channels
+\fBpcm_s24_4be/\-/\-\fP \-\- 24\-bit PCM packed into 4\-byte big\-endian frames, default rate and channels
 .UNINDENT
 .sp
 The list of supported formats and channel layouts can be retrieved using \fB\-\-list\-supported\fP option.
@@ -314,7 +311,7 @@ Where:
 .IP \(bu 2
 \fBid\fP is an arbitrary number in range 100..127, which should uniquely identify encoding on all related senders and receivers
 .IP \(bu 2
-\fBformat\fP defines sample precision and binary representation, e.g. \fBs16_le\fP stands for little\-endian signed 16\-bit integers
+\fBformat\fP defines sample precision and binary representation, e.g. \fBpcm_s24\fP stands for 24\-bit signed integer PCM
 .IP \(bu 2
 \fBrate\fP defines sample rate in Hertz (number of samples per second), e.g. \fB48000\fP
 .IP \(bu 2
@@ -324,9 +321,9 @@ Where:
 Examples:
 .INDENT 0.0
 .IP \(bu 2
-\fB101:s16_be/44100/mono\fP \-\- 16\-bit big\-endian integers, 44.1KHz, 1 channel
+\fB101:pcm_s24/44100/mono\fP \-\- 24\-bit network\-endian integers, 44.1KHz, 1 channel
 .IP \(bu 2
-\fB102:f32_le/48000/stereo\fP \-\- 32\-bit little\-endian floats, 48KHz, 2 channels
+\fB102:pcm_f32/48000/stereo\fP \-\- 32\-bit network\-endian floats, 48KHz, 2 channels
 .UNINDENT
 .sp
 The list of supported formats and channel layouts can be retrieved using \fB\-\-list\-supported\fP option.
@@ -609,7 +606,7 @@ Force specific encoding on the input device:
 .nf
 .ft C
 $ roc\-send \-vv \-s rtp://192.168.0.3:10001 \e
-    \-\-input alsa://hw:1,0 \-\-io\-encoding s32/48000/stereo
+    \-\-input alsa://hw:1,0 \-\-io\-encoding pcm_s32/48000/stereo
 .ft P
 .fi
 .UNINDENT
@@ -621,7 +618,7 @@ Use specific encoding for network packets:
 .sp
 .nf
 .ft C
-$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-\-packet\-encoding 101:s32/48000/stereo
+$ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-\-packet\-encoding 101:pcm_s24/48000/stereo
 .ft P
 .fi
 .UNINDENT
@@ -631,7 +628,7 @@ $ roc\-send \-vv \-s rtp://192.168.0.3:10001 \-\-packet\-encoding 101:s32/48000/
 .sp
 .nf
 .ft C
-$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \-\-packet\-encoding 101:s32/48000/stereo
+$ roc\-recv \-vv \-s rtp://0.0.0.0:10001 \-\-packet\-encoding 101:pcm_s24/48000/stereo
 .ft P
 .fi
 .UNINDENT

docs/sphinx/manuals/roc_copy.rst

@@ -32,9 +32,8 @@ I/O options
 -----------
 
 -i, --input=FILE_URI           Input file URI
---input-format=FILE_FORMAT     Force input file format
+--input-encoding=IO_ENCODING   Input file encoding
 -o, --output=FILE_URI          Output file URI
---output-format=FILE_FORMAT    Force output file format
 --output-encoding=IO_ENCODING  Output file encoding
 --io-frame-len=TIME            I/O frame length, TIME units
 
@@ -101,13 +100,13 @@ Convert sample rate to 24-bit 48k stereo:
 
 .. code::
 
-    $ roc-copy -vv --io-encoding s24/48000/stereo -i file:input.wav -o file:output.wav
+    $ roc-copy -vv --io-encoding pcm_s24/48000/stereo -i file:input.wav -o file:output.wav
 
 Same, but drop output results instead of writing to file (useful for benchmarking):
 
 .. code::
 
-    $ roc-copy -vv --io-encoding s24/48000/stereo -i file:input.wav
+    $ roc-copy -vv --io-encoding pcm_s24/48000/stereo -i file:input.wav
 
 Input from stdin, output to stdout:
 

docs/sphinx/manuals/roc_recv.rst

@@ -36,17 +36,15 @@ Operation options
 Output options
 --------------
 
--o, --output=IO_URI          Output file or device URI
---output-format=FILE_FORMAT  Force output file format
---io-encoding=IO_ENCODING    Output device encoding
---io-latency=TIME            Output device latency, TIME units
---io-frame-len=TIME          Output frame length, TIME units
+-o, --output=IO_URI        Output file or device URI
+--io-encoding=IO_ENCODING  Output device encoding
+--io-latency=TIME          Output device latency, TIME units
+--io-frame-len=TIME        Output frame length, TIME units
 
 Backup input options
 --------------------
 
---backup=IO_URI              Backup file or device URI (used as input when there are no connections)
---backup-format=FILE_FORMAT  Force backup file format
+--backup=IO_URI  Backup file URI (used as input when there are no connections)
 
 Network options
 ---------------
@@ -150,17 +148,17 @@ This option is useful when device supports multiple encodings, or specific file
 
 Where:
 
-* ``format`` defines sample precision and binary representation, e.g. ``s16_le`` stands for little-endian signed 16-bit integers
+* ``format`` defines sample precision and binary representation, e.g. ``pcm_s16_le`` stands for little-endian signed 16-bit integer PCM
 * ``rate`` defines sample rate in Hertz (number of samples per second), e.g. ``48000``
 * ``channels`` defines channel layout, e.g. ``mono`` or ``stereo``
 
 Any component may be set to special value ``-``, which means use default value for the specified output device or file format.
 
 Examples:
 
-* ``s16/44100/mono`` -- 16-bit native-endian integers, 44.1KHz, 1 channel
-* ``f32_le/48000/stereo`` -- 32-bit little-endian floats, 48KHz, 2 channels
-* ``s24_4be/-/-`` -- 24-bit PCM packed into 4-byte big-endian frames, default rate and channels
+* ``pcm_s16/44100/mono`` -- 16-bit native-endian integers, 44.1KHz, 1 channel
+* ``pcm_f32_le/48000/stereo`` -- 32-bit little-endian floats, 48KHz, 2 channels
+* ``pcm_s24_4be/-/-`` -- 24-bit PCM packed into 4-byte big-endian frames, default rate and channels
 
 The list of supported formats and channel layouts can be retrieved using ``--list-supported`` option.
 
@@ -226,14 +224,14 @@ Packet encodings
 Where:
 
 * ``id`` is an arbitrary number in range 100..127, which should uniquely identify encoding on all related senders and receivers
-* ``format`` defines sample precision and binary representation, e.g. ``s16_le`` stands for little-endian signed 16-bit integers
+* ``format`` defines sample precision and binary representation, e.g. ``pcm_s24`` stands for 24-bit signed integer PCM
 * ``rate`` defines sample rate in Hertz (number of samples per second), e.g. ``48000``
 * ``channels`` defines channel layout, e.g. ``mono`` or ``stereo``
 
 Examples:
 
-* ``101:s16_be/44100/mono`` -- 16-bit big-endian integers, 44.1KHz, 1 channel
-* ``102:f32_le/48000/stereo`` -- 32-bit little-endian floats, 48KHz, 2 channels
+* ``101:pcm_s24/44100/mono`` -- 24-bit network-endian integers, 44.1KHz, 1 channel
+* ``102:pcm_f32/48000/stereo`` -- 32-bit network-endian floats, 48KHz, 2 channels
 
 The list of supported formats and channel layouts can be retrieved using ``--list-supported`` option.
 
@@ -457,17 +455,17 @@ Force specific encoding on the output device:
 .. code::
 
     $ roc-recv -vv -s rtp://0.0.0.0:10001 \
-        --output alsa://hw:1,0 --io-encoding s32/48000/stereo
+        --output alsa://hw:1,0 --io-encoding pcm_s32/48000/stereo
 
 Use specific encoding for network packets:
 
 .. code::
 
-    $ roc-send -vv -s rtp://192.168.0.3:10001 --packet-encoding 101:s32/48000/stereo
+    $ roc-send -vv -s rtp://192.168.0.3:10001 --packet-encoding 101:pcm_s24/48000/stereo
 
 .. code::
 
-    $ roc-recv -vv -s rtp://0.0.0.0:10001 --packet-encoding 101:s32/48000/stereo
+    $ roc-recv -vv -s rtp://0.0.0.0:10001 --packet-encoding 101:pcm_s24/48000/stereo
 
 Select the LDPC-Staircase FEC scheme: