ADM (Audio Definition Model) and Dolby Metadata in WAV/RIFF

README.md

@@ -69,6 +69,7 @@ bzip2,
 [csv](doc/formats.md#csv),
 dns,
 dns_tcp,
+[dolby_metadata](doc/formats.md#dolby_metadata),
 elf,
 ether8023_frame,
 exif,

doc/dev.md

@@ -38,16 +38,19 @@ Flags can be struct with bit-fields.
   - Use commit messages with a context prefix to make it easier to find and understand, ex:<br>
   `mp3: Validate sync correctly`
 - Tests:
-  - If possible use a pair of `testdata/file` and `testdata/file.fqtest` where `file.fqtest` is `$ fq dv file` or `$ fq 'dv,torepr' file` if there is `torepr` support.
+  - If possible, add one or more pairs of example input file and expected CLI output, with naming like:
+    - `./format/<format_name>/testdata/<name>.<ext>`, e.g. [`./format/mp4/testdata/aac.mp4`](../format/mp4/testdata/aac.mp4)
+    - and `./format/<format_name>/testdata/<name>.fqtest`, e.g. [`./format/mp4/testdata/aac.fqtest`](../format/mp4/testdata/aac.fqtest)
+  - The latter contents should be `$ go run . dv <file_path>` or `$ go run . 'dv,torepr' <file_path>` if there is `torepr` support.
   - If `dv` produces a lof of output maybe use `dv({array_truncate: 50})` etc
   - Run `go test ./format -run TestFormats/<name>` to test expected output.
   - Run `go test ./format -run TestFormats/<name> -update` to update current output as expected output.
 - If you have format specific documentation:
   - Put it in `format/*/<name>.md` and use `//go:embed <name>.md`/`interp.RegisterFS(..)` to embed/register it.
   - Use simple markdown, just sections (depth starts at 3, `### Section`), paragraphs, lists and links.
-  - No heading section is needs with format name, will be added by `make doc` and fq cli help system.
+  - No heading section is needed with format name, will be added by `make doc` and fq cli help system.
   - Add a `testdata/<name>_help.fqtest` with just `$ fq -h <name>` to test CLI help.
-  - If in doubt look at `mp4.md`/`mp4.go` etc.
+  - If in doubt look at [`mp4.md`](../format/mp4/mp4.md)/[`mp4.go`](../format/mp4/mp4.go) etc.
   - Run `make README.md doc/formats.md` to update md files.
 - Run linter `make lint`
 - Run fuzzer `make fuzz GROUP=<name>`, see usage in Makefile

doc/formats.md

@@ -41,6 +41,7 @@
 |[`csv`](#csv)                                                   |Comma&nbsp;separated&nbsp;values                                                                             |<sub></sub>|
 |`dns`                                                           |DNS&nbsp;packet                                                                                              |<sub></sub>|
 |`dns_tcp`                                                       |DNS&nbsp;packet&nbsp;(TCP)                                                                                   |<sub></sub>|
+|[`dolby_metadata`](#dolby_metadata)                             |Dolby&nbsp;Metadata&nbsp;(Atmos,&nbsp;AC3,&nbsp;Dolby&nbsp;Digital)                                          |<sub></sub>|
 |`elf`                                                           |Executable&nbsp;and&nbsp;Linkable&nbsp;Format                                                                |<sub></sub>|
 |`ether8023_frame`                                               |Ethernet&nbsp;802.3&nbsp;frame                                                                               |<sub>`inet_packet`</sub>|
 |`exif`                                                          |Exchangeable&nbsp;Image&nbsp;File&nbsp;Format                                                                |<sub></sub>|
@@ -129,7 +130,7 @@
 |`vp9_frame`                                                     |VP9&nbsp;frame                                                                                               |<sub></sub>|
 |`vpx_ccr`                                                       |VPX&nbsp;Codec&nbsp;Configuration&nbsp;Record                                                                |<sub></sub>|
 |[`wasm`](#wasm)                                                 |WebAssembly&nbsp;Binary&nbsp;Format                                                                          |<sub></sub>|
-|`wav`                                                           |WAV&nbsp;file                                                                                                |<sub>`id3v2` `id3v1` `id3v11`</sub>|
+|`wav`                                                           |WAV&nbsp;file                                                                                                |<sub>`id3v2` `id3v1` `id3v11` `dolby_metadata`</sub>|
 |`webp`                                                          |WebP&nbsp;image                                                                                              |<sub>`exif` `vp8_frame` `icc_profile` `xml`</sub>|
 |[`xml`](#xml)                                                   |Extensible&nbsp;Markup&nbsp;Language                                                                         |<sub></sub>|
 |`yaml`                                                          |YAML&nbsp;Ain't&nbsp;Markup&nbsp;Language                                                                    |<sub></sub>|
@@ -590,6 +591,33 @@ $ 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 (Atmos, AC3, Dolby Digital).
+
+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' adm-bwf.wav
+```
+
+RIFF / WAV / Broadcast Wave Format (BWF) chunks:
+- `<chna>` Track UIDs of Audio Definition Model
+- `<axml>` BWF XML Metadata, e.g. for Audio Definition Model ambisonics and elements
+
+### 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
+- https://tech.ebu.ch/files/live/sites/tech/files/shared/tech/tech3285s6.pdf
+- https://github.com/DolbyLaboratories/dbmd-atmos-parser
+- https://github.com/MediaArea/MediaInfoLib/tree/Source/MediaInfo/Audio/File_DolbyAudioMetadata.cpp
+
 ## fit
 Garmin Flexible and Interoperable Data Transfer.
 

format/format.go

@@ -92,6 +92,7 @@ var (
 	CSV                 = &decode.Group{Name: "csv"}
 	DNS                 = &decode.Group{Name: "dns"}
 	DNS_TCP             = &decode.Group{Name: "dns_tcp"}
+	Dolby_Metadata      = &decode.Group{Name: "dolby_metadata"}
 	ELF                 = &decode.Group{Name: "elf"}
 	Ether_8023_Frame    = &decode.Group{Name: "ether8023_frame"}
 	Exif                = &decode.Group{Name: "exif"}

format/riff/adm.go

@@ -0,0 +1,30 @@
+package riff
+
+// Audio Definition Model
+// https://adm.ebu.io/background/what_is_the_adm.html
+// https://tech.ebu.ch/publications/tech3285s7
+// https://tech.ebu.ch/publications/tech3285s5
+
+import (
+	"github.com/wader/fq/pkg/decode"
+)
+
+func chnaDecode(d *decode.D) {
+	d.FieldU16("num_tracks")
+	d.FieldU16("num_uids")
+	d.FieldArray("audio_ids", func(d *decode.D) {
+		for !d.End() {
+			d.FieldStruct("audio_id", func(d *decode.D) {
+				d.FieldU16("track_index")
+				d.FieldUTF8("uid", 12)
+				d.FieldUTF8("track_format_id_reference", 14)
+				d.FieldUTF8("pack_format_id_reference", 11)
+				d.FieldRawLen("padding", 8)
+			})
+		}
+	})
+}
+
+func axmlDecode(d *decode.D) {
+	d.FieldUTF8("xml", int(d.BitsLeft())/8)
+}

format/riff/adm.md

@@ -0,0 +1,22 @@
+[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:
+```bash
+$ fq -d wav '.chunks[] | select(.id | IN("chna", "axml")) | tovalue' amd-bwf.wav
+
+# Extract ADM <axml> chunk objects definitions xml content
+$ fq -r -d wav '.chunks[] | select(.id | IN("axml")) | .xml | tovalue' amd-bwf.wav | tee axml-content.xml
+```
+
+### 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

format/riff/aiff.go

@@ -54,7 +54,7 @@ func aiffDecode(d *decode.D) any {
 			}
 			return id, size
 		},
-		func(d *decode.D, id string, path path) (bool, any) {
+		func(d *decode.D, id string, path path, size int64) (bool, any) {
 			switch id {
 			case "FORM":
 				riffType = d.FieldUTF8("format", 4, d.StrAssert(aiffRiffType))

format/riff/avi.go

@@ -238,7 +238,7 @@ func aviDecodeEx(d *decode.D, ai format.AVI_In, extendedChunk bool) {
 			size := d.FieldU32("size")
 			return id, int64(size)
 		},
-		func(d *decode.D, id string, path path) (bool, any) {
+		func(d *decode.D, id string, path path, size int64) (bool, any) {
 			switch id {
 			case "RIFF":
 				foundRiffType = d.FieldUTF8("type", 4, d.StrAssert(requiredRiffType))

format/riff/common.go

@@ -19,11 +19,11 @@ func (p path) topData() any {
 	return p[len(p)-1].data
 }
 
-func riffDecode(d *decode.D, path path, headFn func(d *decode.D, path path) (string, int64), chunkFn func(d *decode.D, id string, path path) (bool, any)) {
+func riffDecode(d *decode.D, path path, headFn func(d *decode.D, path path) (string, int64), chunkFn func(d *decode.D, id string, path path, size int64) (bool, any)) {
 	id, size := headFn(d, path)
 
 	d.FramedFn(size*8, func(d *decode.D) {
-		hasChildren, data := chunkFn(d, id, path)
+		hasChildren, data := chunkFn(d, id, path, size)
 		if hasChildren {
 			np := append(path, pathEntry{id: id, data: data})
 			d.FieldArray("chunks", func(d *decode.D) {
@@ -36,9 +36,9 @@ func riffDecode(d *decode.D, path path, headFn func(d *decode.D, path path) (str
 		}
 	})
 
-	wordAlgin := d.AlignBits(16)
-	if wordAlgin != 0 {
-		d.FieldRawLen("align", int64(wordAlgin))
+	wordAlign := d.AlignBits(16)
+	if wordAlign != 0 {
+		d.FieldRawLen("align", int64(wordAlign))
 	}
 }
 
@@ -58,6 +58,10 @@ var chunkIDDescriptions = scalar.StrMapDescription{
 
 	"dmlh": "Extended AVI header",
 
+	"chna": "Track UIDs of Audio Definition Model",
+	"axml": "Audio Definition Model ambisonics and elements",
+	"dbmd": "Dolby Metadata, e.g. Atmos, AC3, Dolby Digital [Plus]",
+
 	"ISMP": "SMPTE timecode",
 	"IDIT": "Time and date digitizing commenced",
 	"IARL": "Archival Location. Indicates where the subject of the file is archived.",