[FFmpeg-devel] [PATCH 1/2] avcodec/s302m: document ST 302 format

[knneth at gmail.com]

From: Kenneth Klette Jonassen <kenneth at bridgetech.tv>

ST 302:2007 is the latest iteration of the transport specification
and replaces the older SMPTE 302M name. To avoid possible end-user
confusion, we'll update the description in source code comments only.

Fill in a few important pieces of the bitstream documentation that is
specific to ST 302, so that it is possible to understand the decoder
without access to the ST 302 spec (which is behind a paywall).

Signed-off-by: Kenneth Klette Jonassen <kenneth at bridgetech.tv>
---
 libavcodec/s302m.c    | 26 +++++++++++++++++++-------
 libavcodec/s302menc.c |  3 ++-
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/libavcodec/s302m.c b/libavcodec/s302m.c
index 584b58e..1e49e9e 100644
--- a/libavcodec/s302m.c
+++ b/libavcodec/s302m.c
@@ -1,5 +1,6 @@
 /*
- * SMPTE 302M decoder
+ * ST 302 decoder (aka. SMPTE 302M)
+ * Mapping of AES3 Data into MPEG-2 Transport Stream
  * Copyright (c) 2008 Laurent Aimar <fenrir at videolan.org>
  * Copyright (c) 2009 Baptiste Coudurier <baptiste.coudurier at gmail.com>
  *
@@ -46,12 +47,23 @@ static int s302m_parse_frame_header(AVCodecContext *avctx, const uint8_t *buf,
     }
 
     /*
-     * AES3 header :
-     * size:            16
-     * number channels   2
-     * channel_id        8
-     * bits per samples  2
-     * alignments        4
+     * ST 302 AES3 data header:
+     * size:            16  bytes of data payload (excl. this header)
+     * number channels   2  number of data channels
+     * channel_id        8  first data channel in packet
+     * bits per sample   2  16/20/24 bits (0x3 is reserved value)
+     * alignment         4  reserved/zero
+     *
+     * Followed by ST 302 AES3 data payload containing AES3 subframes
+     *
+     * Each subframe contains one data word + 4 bits VUCF (AES3 VUC bits +
+     * Framing bit). Framing bit indicates first subframe of AES3 block and
+     * the start of U(ser data) and C(hannel status) information.
+     * Framing bit replaces Parity bit in regular AES3 subframes.
+     * See an AES3 reference (like Wikipedia) for more information.
+     *
+     * Word rate (sample rate) shall be 48 kHz, and shall be locked
+     * to the 27MHz transport clock.
      */
 
     h = AV_RB32(buf);
diff --git a/libavcodec/s302menc.c b/libavcodec/s302menc.c
index b04a54e..99e7350 100644
--- a/libavcodec/s302menc.c
+++ b/libavcodec/s302menc.c
@@ -1,5 +1,6 @@
 /*
- * SMPTE 302M encoder
+ * ST 302 encoder (aka. SMPTE 302M)
+ * Mapping of AES3 Data into MPEG-2 Transport Stream
  * Copyright (c) 2010 Google, Inc.
  * Copyright (c) 2013 Darryl Wallace <wallacdj at gmail.com>
  *
-- 
1.8.3.1