AVTP Audio Format (AAF) Plugin
==============================
Overview
--------
The AAF plugin is a PCM plugin that uses Audio Video Transport Protocol (AVTP)
to transmit/receive audio samples through a Time-Sensitive Network (TSN)
capable network. The plugin enables media applications to easily implement AVTP
Talker and Listener functionalities.
AVTP is designed to take advantage of generalized Precision Time Protocol
(gPTP) and Forwarding and Queuing Enhancements for Time-Sensitive Streams
(FQTSS). gPTP ensures AVTP talkers and listeners share the same time reference
so the presentation time from AVTP can be used to inform when PCM samples
should be presented to the application layer. FQTSS provides bandwidth
reservation and traffic prioritization for the AVTP stream.
gPTP functionality is provided by the Linuxptp project while FQTSS
functionality is provided by Linux Traffic Control system since kernel version
4.15.
gPTP Setup
----------
The Linuxptp project provides the ptp4l daemon, which synchronizes the PTP
clock from NIC, and the pmc tool which communicates with ptp4l to get/set
some runtime settings. The project also provides the phc2sys daemon which
synchronizes the PTP clock and system clock.
The AAF Plugin requires system clock is synchronized with PTP clock and TAI
offset is properly set in the kernel. ptp4l and phc2sys can be set up in many
different ways, below we provide an example that fullfils the plugin
requirements. For further information check ptp4l(8) and phc2sys(8).
In the following instructions, replace $IFNAME by your PTP capable NIC
interface. The gPTP.cfg file mentioned below can be found in /usr/share/
doc/linuxptp/ (depending on your distro).
Synchronize PTP clock with PTP time:
$ ptp4l -f gPTP.cfg -i $IFNAME
Enable TAI offset to be automatically set by phc2sys:
$ pmc -u -t 1 -b 0 'SET GRANDMASTER_SETTINGS_NP \
clockClass 248 clockAccuracy 0xfe \
offsetScaledLogVariance 0xffff \
currentUtcOffset 37 leap61 0 leap59 0 \
currentUtcOffsetValid 1 pTimescale 1 \
timeTraceable 1 frequencyTraceable 0 timeSource 0xa0'
Synchronize system clock with PTP clock:
$ phc2sys -f gPTP.cfg -s $IFNAME -c CLOCK_REALTIME -w
The commands above should be run on both AVTP Talker and Listener hosts.
Traffic Control Setup
---------------------
The Linux Traffic Control system provides the mqprio and cbs qdiscs which
enable FQTSS on Linux. Below we provide an example to configure those qdiscs in
order to transmit an AAF stream with the following features: class A, 6 audio
frames per AVTPDU, 48 kHz sampling rate, 16-bit sample size, stereo. For
further information on how to configure these qdiscs check tc-mqprio(8) and
tc-cbs(8) man pages.
On the host that will run as AVTP Talker (i.e. plugin in playback mode), run
the following commands:
Configure mpqrio qdisc (replace $MQPRIO_HANDLE_ID by an unused handle ID):
$ tc qdisc add dev $IFNAME parent root handle $MQPRIO_HANDLE_ID \
mqprio num_tc 3 map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \
queues 1@0 1@1 2@2 hw 0
Configure cbs qdisc (replace $CBS_HANDLE_ID by an unused handle ID):
$ tc qdisc replace dev $IFNAME parent $MQPRIO_HANDLE_ID:1 \
handle $CBS_HANDLE_ID cbs idleslope 5760 \
sendslope -994240 hicredit 9 locredit -89 offload 1
The plugin implements a transmission mechanism that relies on ETF qdisc so make
sure it is properly configured in the system. It could be configured many way,
below follows an example.
$ tc qdisc add dev $IFNAME parent $CBS_HANDLE_ID:1 etf \
clockid CLOCK_TAI delta 500000 offload
No Traffic Control configuration is required at the host running as AVTP
Listener.
Plugin Dependencies
-------------------
The AAF plugin uses libavtp to handle AVTP packetization. Libavtp source code
can be found in https://github.com/AVnu/libavtp as well as instructions to
build and install it.
The plugin also depends on some kernel API headers such as linux/if_ether.h so
make sure you have them installed in your system.
If libavtp or the kernel headers aren't detected by configure, the plugin isn't
built.
Plugin Configuration
--------------------
The plugin parameters are passed via ALSA configuration file. They are defined
as follows:
* ifname: Network interface used to transmit/receive AVTP packets.
* addr: Stream destination MAC address.
* prio: Priority used by the plugin to transmit AVTP traffic. This
option is relevant only when operating in playback mode.
* streamid: Stream ID associated with the AAF stream transmitted or
received by the plugin.
* mtt: Maximum Transit Time (in microseconds) as defined in AVTP spec
section 4.3.3. This option is relevant only when operating in
playback mode.
* time_uncertainty: Maximum Time Uncertainty (in microseconds) as
defined by AVTP spec section 4.3.3. This option is relevant only when
operating in playback mode.
* frames_per_pdu: Number of audio frames transmitted in one AVTPDU.
* ptime_tolerance: Presentation time tolerance in microseconds.
AVTPDUs with presentation time off by +- ptime_tolerance are not
considered invalid. This option is relevant only when operating in
capture mode.
Plugin Usage
------------
The plugin provides the PCM type "aaf". Configure an AAF PCM virtual device
according to the AAF stream you want to transmit or receive. A hypothetical
configuration for the stream described in the 'FQTSS Setup' section is shown
below:
pcm.aaf0 {
type aaf
ifname eth0
addr 01:AA:AA:AA:AA:AA
prio 3
streamid AA:BB:CC:DD:EE:FF:0000
mtt 2000
time_uncertainty 125
frames_per_pdu 6
ptime_tolerance 100
}
Put the above to ~/.asoundrc (or /etc/asound.conf), and use the AAF PCM virtual
device 'aaf0' with your favorite alsa-utils tool. Note that the plugin requires
the period size is multiple of the 'frames_per_pdu' configuration.
For example, to stream the pink noise generated by 'speaker-test', run:
$ speaker-test -F S16_BE -c 2 -r 48000 -D aaf0 -p 12500
To receive the AAF stream generated by the command above, run the following
command in another host:
$ arecord -t raw -f S16_BE -c 2 -r 48000 -D aaf0 -vv /dev/null -F 12500
If you want to playback the contents of the AAF stream, change the command-line
above so the output from 'arecord' is redirected to 'aplay', or simply use the
'alsaloop' tool.