Docs and minor cleanup

wader · Aug 21, 2024 · 83abdda · 83abdda
1 parent 1e0ba55
commit 83abdda
Show file tree

Hide file tree

Showing 5 changed files with 50 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -35,6 +35,7 @@ It was originally designed to query, inspect and debug media codecs and containe
 [aac_frame](doc/formats.md#aac_frame),
 adts,
 adts_frame,
+[adm](doc/formats.md#adm),
 aiff,
 amf0,
 apev2,
@@ -53,6 +54,7 @@ avc_sei,
 avc_sps,
 [avi](doc/formats.md#avi),
 [avro_ocf](doc/formats.md#avro_ocf),
+[axml](doc/formats.md#adm),
 [bencode](doc/formats.md#bencode),
 bitcoin_blkdat,
 [bitcoin_block](doc/formats.md#bitcoin_block),
@@ -66,7 +68,9 @@ bsd_loopback_frame,
 bzip2,
 [caff](doc/formats.md#caff),
 [cbor](doc/formats.md#cbor),
+[chna](doc/formats.md#adm),
 [csv](doc/formats.md#csv),
+[dolby_metadata](doc/formats.md#dolby_metadata),
 dns,
 dns_tcp,
 elf,

diff --git a/doc/formats.md b/doc/formats.md
@@ -7,6 +7,7 @@
 |[`aac_frame`](#aac_frame)                                       |Advanced&nbsp;Audio&nbsp;Coding&nbsp;frame                                                                   |<sub></sub>|
 |`adts`                                                          |Audio&nbsp;Data&nbsp;Transport&nbsp;Stream                                                                   |<sub>`adts_frame`</sub>|
 |`adts_frame`                                                    |Audio&nbsp;Data&nbsp;Transport&nbsp;Stream&nbsp;frame                                                        |<sub>`aac_frame`</sub>|
+|[`adm`](#adm)                                                   |Audio&nbsp;Definition&nbsp;Model                                                                             |<sub>`riff`</sub>|
 |`aiff`                                                          |Audio&nbsp;Interchange&nbsp;File&nbsp;Format                                                                 |<sub></sub>|
 |`amf0`                                                          |Action&nbsp;Message&nbsp;Format&nbsp;0                                                                       |<sub></sub>|
 |`apev2`                                                         |APEv2&nbsp;metadata&nbsp;tag                                                                                 |<sub>`image`</sub>|
@@ -25,6 +26,7 @@
 |`avc_sps`                                                       |H.264/AVC&nbsp;Sequence&nbsp;Parameter&nbsp;Set                                                              |<sub></sub>|
 |[`avi`](#avi)                                                   |Audio&nbsp;Video&nbsp;Interleaved                                                                            |<sub>`avc_au` `hevc_au` `mp3_frame` `flac_frame`</sub>|
 |[`avro_ocf`](#avro_ocf)                                         |Avro&nbsp;object&nbsp;container&nbsp;file                                                                    |<sub></sub>|
+|[`axml`](#adm)                                                  |Audio&nbsp;Definition&nbsp;Model&nbsp;<axml>&nbsp;Chunk                                                      |<sub>`riff`</sub>|
 |[`bencode`](#bencode)                                           |BitTorrent&nbsp;bencoding                                                                                    |<sub></sub>|
 |`bitcoin_blkdat`                                                |Bitcoin&nbsp;blk.dat                                                                                         |<sub>`bitcoin_block`</sub>|
 |[`bitcoin_block`](#bitcoin_block)                               |Bitcoin&nbsp;block                                                                                           |<sub>`bitcoin_transaction`</sub>|
@@ -38,7 +40,9 @@
 |`bzip2`                                                         |bzip2&nbsp;compression                                                                                       |<sub>`probe`</sub>|
 |[`caff`](#caff)                                                 |Live2D&nbsp;Cubism&nbsp;archive                                                                              |<sub>`probe`</sub>|
 |[`cbor`](#cbor)                                                 |Concise&nbsp;Binary&nbsp;Object&nbsp;Representation                                                          |<sub></sub>|
+|[`chna`](#adm)                                                  |Audio&nbsp;Definition&nbsp;Model&nbsp;<chna>&nbsp;Chunk                                                      |<sub>`riff`</sub>|
 |[`csv`](#csv)                                                   |Comma&nbsp;separated&nbsp;values                                                                             |<sub></sub>|
+|[`dolby_metadata`](#dolby_metadata)                             |Dolby&nbsp;Metadata&nbsp;(Atmos,&nbsp;AC3,&nbsp;Digital&nbspPlus)                                            |<sub>`riff`</sub>|
 |`dns`                                                           |DNS&nbsp;packet                                                                                              |<sub></sub>|
 |`dns_tcp`                                                       |DNS&nbsp;packet&nbsp;(TCP)                                                                                   |<sub></sub>|
 |`elf`                                                           |Executable&nbsp;and&nbsp;Linkable&nbsp;Format                                                                |<sub></sub>|
@@ -179,6 +183,27 @@ Decode value as aac_frame
 ... | aac_frame({object_type:1})
 ```
 
+## adm
+[Audio Definition Model](https://adm.ebu.io/background/what_is_the_adm.html) including 3D Audio.
+
+RIFF / WAV / Broadcast Wave Format (BWF) chunks:
+- `<chna>` Chunk, Track UIDs of Audio Definition Model
+-	`<axml>` Chunk, BWF XML Metadata, e.g. for Audio Definition Model ambisonics and elements
+
+### Examples
+Decode ADM configuration from `<chna>` and `<axml>` chunks:
+```
+$ fq -d wav '.chunks[] | select(.id | IN("chna", "axml")) | tovalue' bwf.wav
+```
+
+### Authors
+- [@johnnymarnell](https://johnnymarnell.github.io), original author
+
+### References
+- https://adm.ebu.io/background/what_is_the_adm.html
+- https://tech.ebu.ch/publications/tech3285s7
+- https://tech.ebu.ch/publications/tech3285s5
+
 ## apple_bookmark
 Apple BookmarkData.
 
@@ -590,6 +615,23 @@ $ fq -d csv -o comma="\t" to_csv file.tsv
 $ fq -d csv '.[0] as $t | .[1:] | map(with_entries(.key = $t[.key]))' file.csv
 ```
 
+## dolby_metadata
+Dolby Metadata from `<dbmd>` chunk of RIFF / WAV / Broadcast Wave Format (BWF),
+including Dolby Atmos, AC3, Dolby Digital \[Plus\], and Dolby Audio Info (e.g. LUFS, True Peak).
+
+### Examples
+Decode Dolby metadata from `<dbmd>` chunk:
+```
+$ fq -d wav '.chunks[] | select(.id | IN("dbmd")) | tovalue' bwf.wav
+```
+
+### References
+- https://tech.ebu.ch/files/live/sites/tech/files/shared/tech/tech3285s6.pdf
+- https://github.com/DolbyLaboratories/dbmd-atmos-parser
+
+### Authors
+- [@johnnymarnell](https://johnnymarnell.github.io), original author
+
 ## fit
 Garmin Flexible and Interoperable Data Transfer.
 
@@ -782,7 +824,6 @@ LevelDB Table.
 - Zstandard uncompression is not implemented yet.
 
 ### Authors
-
 - [@mikez](https://github.com/mikez), original author
 
 ### References

diff --git a/format/riff/adm.go b/format/riff/adm.go
@@ -25,7 +25,6 @@ func chnaDecode(d *decode.D, size int64) {
 }
 
 func axmlDecode(d *decode.D, size int64) {
-	// fmt.Println("test axml")
 	// TODO(jmarnell): this chunk is all variable xml, so leave as is?
 	d.FieldRawLen("xml", size*8)
 }
diff --git a/format/riff/common.go b/format/riff/common.go
@@ -60,7 +60,7 @@ var chunkIDDescriptions = scalar.StrMapDescription{
 
 	"chna": "<chna> Chunk, Track UIDs of Audio Definition Model",
 	"axml": "<axml> Chunk, BWF XML Metadata, e.g. for Audio Definition Model ambisonics and elements",
-	"dbmd": "Dolby Metadata",
+	"dbmd": "Dolby Metadata, e.g. Atmos, AC3, Dolby Digital [Plus]",
 
 	"ISMP": "SMPTE timecode",
 	"IDIT": "Time and date digitizing commenced",

diff --git a/format/riff/dolby.go b/format/riff/dolby.go
@@ -54,15 +54,14 @@ func dbmdDecode(d *decode.D, size int64) any {
 					d.FieldRawLen("unknown_segment_raw", int64(segmentSize*8))
 				}
 
-				fmt.Println("bytesRead: ", (bitsLeft-d.BitsLeft())/8, " segment size:", segmentSize)
-
 				bytesRemaining := (bitsLeft-d.BitsLeft())/8 - int64(segmentSize)
 				if bytesRemaining < 0 {
 					d.Fatalf("Read too many bytes for segment %d, read %d over, expected %d", segmentID, -bytesRemaining, segmentSize)
 				} else if bytesRemaining > 0 {
 					d.FieldValueUint("SKIPPED_BYTES", uint64(bytesRemaining))
 					d.SeekRel((int64(segmentSize) - bytesRemaining) * 8)
 				}
+
 				d.FieldU8("metadata_segment_checksum")
 			})
 		}
@@ -227,7 +226,6 @@ func parseAudioInfo(d *decode.D) {
 
 func parseDolbyAtmos(d *decode.D, size uint64) {
 	d.FieldValueStr("metadata_segment_type", "dolby_atmos")
-	bitsLeft := d.BitsLeft()
 
 	// d.SeekRel(32 * 8)
 	str := d.FieldUTF8Null("atmos_dbmd_content_creation_preamble")
@@ -248,14 +246,10 @@ func parseDolbyAtmos(d *decode.D, size uint64) {
 
 	d.SeekRel(15 * 8)
 	d.SeekRel(80 * 8)
-
-	fmt.Println("test", int64(size)*8-(bitsLeft-d.BitsLeft()))
-	d.SeekRel(int64(size)*8 - (bitsLeft - d.BitsLeft()))
 }
 
 func parseDolbyAtmosSupplemental(d *decode.D, size uint64) {
 	d.FieldValueStr("metadata_segment_type", "dolby_atmos_supplemental")
-	bitsLeft := d.BitsLeft()
 
 	sync := d.FieldU32LE("dasms_sync")
 	d.FieldValueBool("dasms_sync_valid", sync == 0xf8726fbd)
@@ -281,8 +275,8 @@ func parseDolbyAtmosSupplemental(d *decode.D, size uint64) {
 				nonZeroBytes = append(nonZeroBytes, fmt.Sprintf("%d", b))
 			}
 		}
-		// TODO(jmarnell): I think the +3dB trim settings are here. Would like this as an array of numbers
-		// 			at least, instead of CSV string
+		// TODO(jmarnell): I think the +3dB trim settings are here.
+		//		Would like this at least as an array of numbers, instead of this CSV string
 		d.FieldValueStr("trim_defs", strings.Join(nonZeroBytes, ", "))
 
 		i++
@@ -297,7 +291,4 @@ func parseDolbyAtmosSupplemental(d *decode.D, size uint64) {
 		d.FieldValueUint("render_mode", mode)
 		d.FieldValueStr("render_mode_type", binaural[mode])
 	})
-
-	fmt.Println("test", int64(size)*8-(bitsLeft-d.BitsLeft()))
-	d.SeekRel(int64(size)*8 - (bitsLeft - d.BitsLeft()))
 }