From 7cbdd3dab6beaa9252dff253d6dbcf61bce1ee26 Mon Sep 17 00:00:00 2001 From: Jamie Hardt Date: Tue, 7 Nov 2023 11:23:40 -0800 Subject: [PATCH 1/3] Added a manpage --- data/share/man/man1/wavinfo.1 | 72 +++++++++++++++++++++++++++++++++++ pyproject.toml | 3 ++ 2 files changed, 75 insertions(+) create mode 100644 data/share/man/man1/wavinfo.1 diff --git a/data/share/man/man1/wavinfo.1 b/data/share/man/man1/wavinfo.1 new file mode 100644 index 0000000..199bd67 --- /dev/null +++ b/data/share/man/man1/wavinfo.1 @@ -0,0 +1,72 @@ +.TH mw 1 "2023-05-30" "Jamie Hardt" "User Manuals" +.SH NAME +wavinfo \- probe wave files for metadata +.SH SYNOPSIS +.SY wavinfo +.I "[\-\-adm]" +.I "[\-\-ixml]" +.I FILE ... +.SH DESCRIPTION +.B wavinfo +extracts embedded metadata from WAVE and RF64/WAVE sound files, with an +emphasis on film, video and professional music production metadata. + +.SH OPTIONS +.IP "(no options)" +With no options, +.B wavinfo +will emit a JSON (Javascript Object Notation) object containing all +detected metadata. +.IP "\-\-adm" +Output any Audio Definition Model (ADM) metadata in +.BR FILE . +.IP "\-\-ixml" +Output any iXML metdata in +.BR FILE . +.IP "\-h, \-\-help" +Print brief help. +.SH DETAILED DESCRIPTION +.B wavinfo +collects metadata according to different +.IR scopes . +.SS METADATA SCOPES +.IP fmt +Basic audio properties: sample format, sample rate, channel count, etc. +.IP data +Size and frame count of the WAVE file's +.I data +segment. +.IP cues +Timed cue points, labels, notes and time ranges. +.IP bext +Broadcast-WAV metadata: description, originator, date and time, UMID. +.IP ixml +A selection of parsed iXML fields: track list, project, scene, take, tape, +family name, family uid. For the full iXML document use the +.IR \-\-ixml +command option. +.IP adm +EBU Audio Definition Model (ADM) metadata: Programme, channels. For the full +ADM +.I +document use the +.IR \-\-adm +command option. +.IP dolby +Dolby bitstream and Atmos metadata. +.IP info +INFO metadata fields: IART (artist), ICMT (comment), etc. +.SH EXIT STATUS +.IP 0 +On user quit. +.SH AUTHOR +Jamie Hardt +.SH BUGS +Issue submissions, feature requests, pull requests and other contributions +are welcome and should be directed at +.BR wavinfo 's +home page on GitHub: +.RS 4 +.I https://github.com/iluvcapra/wavinfo +.\" .SH SEE ALSO +.\" .BR "ffmpeg" "(1)," diff --git a/pyproject.toml b/pyproject.toml index e7e7a3f..f25ed0c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -54,6 +54,9 @@ wavinfo = 'wavinfo.__main__:main' [project.scripts] wavinfo = "wavinfo.__main__:main" +[tool.flit.external-data] +directory = "data" + [tool.pyright] typeCheckingMode = "basic" From 3323aef36cc1aec32ef676989079351b75cdbecb Mon Sep 17 00:00:00 2001 From: Jamie Hardt Date: Tue, 7 Nov 2023 11:25:38 -0800 Subject: [PATCH 2/3] Typos --- data/share/man/man1/wavinfo.1 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/data/share/man/man1/wavinfo.1 b/data/share/man/man1/wavinfo.1 index 199bd67..2d3c84e 100644 --- a/data/share/man/man1/wavinfo.1 +++ b/data/share/man/man1/wavinfo.1 @@ -1,4 +1,4 @@ -.TH mw 1 "2023-05-30" "Jamie Hardt" "User Manuals" +.TH wavinfo 1 "2023-11-07" "Jamie Hardt" "User Manuals" .SH NAME wavinfo \- probe wave files for metadata .SH SYNOPSIS @@ -10,7 +10,6 @@ wavinfo \- probe wave files for metadata .B wavinfo extracts embedded metadata from WAVE and RF64/WAVE sound files, with an emphasis on film, video and professional music production metadata. - .SH OPTIONS .IP "(no options)" With no options, From e9bebcd022f9726c82a5df1ecce1d16941887a87 Mon Sep 17 00:00:00 2001 From: Jamie Hardt Date: Tue, 7 Nov 2023 14:27:00 -0800 Subject: [PATCH 3/3] More manpage stuff --- data/share/man/man1/wavinfo.1 | 7 +- data/share/man/man7/wavinfo.7 | 190 ++++++++++++++++++++++++++++++++++ 2 files changed, 195 insertions(+), 2 deletions(-) create mode 100644 data/share/man/man7/wavinfo.7 diff --git a/data/share/man/man1/wavinfo.1 b/data/share/man/man1/wavinfo.1 index 2d3c84e..58fd7d6 100644 --- a/data/share/man/man1/wavinfo.1 +++ b/data/share/man/man1/wavinfo.1 @@ -59,13 +59,16 @@ INFO metadata fields: IART (artist), ICMT (comment), etc. .IP 0 On user quit. .SH AUTHOR -Jamie Hardt +Jamie Hardt +.UR https://github.com/iluvcapra +.UE .SH BUGS Issue submissions, feature requests, pull requests and other contributions are welcome and should be directed at .BR wavinfo 's home page on GitHub: .RS 4 -.I https://github.com/iluvcapra/wavinfo +.UR https://github.com/iluvcapra/wavinfo +.UE .\" .SH SEE ALSO .\" .BR "ffmpeg" "(1)," diff --git a/data/share/man/man7/wavinfo.7 b/data/share/man/man7/wavinfo.7 new file mode 100644 index 0000000..f370925 --- /dev/null +++ b/data/share/man/man7/wavinfo.7 @@ -0,0 +1,190 @@ +.TH waveinfo 7 "2023-11-07" "Jamie Hardt" "Miscellaneous Information Manuals" +.SH NAME +wavinfo \- information about wave sound file metadata +.\" .SH DESCRIPTION +.SH CHUNK MENAGERIE +A list of chunks that you may find in a wave file from our experience. +.SS Essential WAV Chunks +.IP fmt +Defines the format of the audio in the +.I data +chunk: the audio codec, the sample rate, bit depth, channel count, block +alignment and other data. May take an "extended" form, with additional data +(such as channel speaker assignments) if there are more than two channels in +the file or if it is a compressed format. +.IP data +The audio data itself. PCM audio data is always stored as interleaved samples. +.IP JUNK +A region of the file not currently in use. Clients sometimes add these before +the +.I data +chunk in order to align the beginning of the audio data with a memory page +boundary (this can make memory-mapped reads from a wave file a little more +efficient). A +.I JUNK +chunk is often placed at the beginning of a WAVE file to reserve space for +a +.I ds64 +chunk that will be written to the file at the end of recording, in the event +that after the file is finalized, it exceeds the RIFF size limit. Thus a WAVE +file can be upgraded in-place to an RF64 without re-writing the audio data. +.IP fact +Fact chunks record the number of samples in the decoded audio stream. It's only +present in WAVE files that contain compressed audio. +.IP "LIST or list" +(Both have been seen) Not a chunk type itself but signals to a RIFF parser that +this chunk contains chunks itself. A LIST chunk's payload will begin with a +four-character code identifying the form of the list, and is then followed +by chunks of the standard key-length-data form, which may themselves be +LISTs that themselves contain child chunks. WAVE files don't tend to have a +very deep heirarchy of chunks, compared to AVI files. +.SS RIFF Metadata +The RIFF container format has a metadata system common to all RIFF files, WAVE +being the most common at present, AVI being another very common format +historically. +.IP INFO +A +.I LIST +form containing a flat list of chunks, each containing text metadata. The role +of the string, like "Artist", "Composer", "Comment", "Engineer" etc. are given +by the four-character code: "Artist" is +.IR IART , +Composer is +.IR ICMP , +engineer is +.IR IENG , +Comment is +.IR ICMT , +etc. +.IP cue +A binary list of cues, which are timed points within the audio data. +.IP adtl +A +.I LIST +form containing text labels +.RI ( labl ) +for the cues in the +.I cue +chunk, "notes" +.RI ( note , +which are structurally identical to +.I labl +but hosts tend to use notes for longer text), and "length text" +.I ltxt +metadata records, which can give a cue a length, making it a range, and a text +field that defines its own encoding. +.IP CSET +Defines the character set for all text fields in +.IR INFO , +.I adtl +and other RIFF-defined text fields. By default, all of the text in RIFF +metadata fields is Windows Latin 1/ISO 8859-1, though as time passes many +clients have simply taken to sticking UTF-8 into these fields. The +.I CSET +cannot represent UTF-8 as a valid option for text encoding, it only speaks +Windows codepages, and we've never seen one in a WAVE file in any event and +it's vanishingly likely an audio app would recognize one if it saw it. +.SS Broadcast-WAVE Metadata +Broadcast-WAVE is a set of extensions to WAVE files to facilitate media +production maintained by the EBU. +.IP bext +A multi-field structure containing mostly fixed-width text data capturing +essential production information: a 256 character free description field, +originator name and a unique reference, recording date and time, a frame-based +timestamp for sample-accurate recording time, and a coding history record. The +extended form of the structure can hold a SMPTE UMID (a kind of UUID, which +may also contain timestamp and geolocation data) and pre-computed program +loudness measurements. +.IP peak +A binary data structure containing the peak envelope for the audio data, for +use by clients to generate a waveform overview. +.SS Audio Definition Model Metadata +Audio Definition Model (ADM) metadata is a metadata standard for audio +broadcast and distribution maintained by the ITU. +.IP chna +A binary list that associates individual channels in the file to entities +in the ADM XML document stored in the +.I axml +chunk. A +.I chna +chunk will always appear with an +.I axml +chunk and vice versa. +.IP axml +Contains an XML document with Audio Definition Model metadata. ADM metadata +describes the program the WAVE file belongs to, role, channel assignment, +and encoding properties of individual channels in the WAVE file, and if the +WAVE file contains object-based audio, it will also give all of the positioning +and panning automation envelopes. +.IP bxml +This is defined by the ITU as a gzip-compressed version of the +.I axml +chunk. +.IP sxml +This is a hybrid binary/gzip-compressed-XML chunk that associates ADM +documents with timed ranges of a WAVE file. +.SS Dolby Metadata +.IP dbmd +Records hints for Dolby playback applications for downmixing, level +normalization and other things. +.SS Proprietary Chunks +.IP ovwf +.B (Pro Tools) +Pre-computed waveform overview data. +.IP regn +.B (Pro Tools) +Region and cue point metadata. +.SS Chunks of Unknown Purpose +.IP elm1 +.IP minf +.IP umid +.SH HISTORY +The oldest document that defines the form of a Wave file is the +.I Multimedia Programming Interface and Data Specifications 1.0 +of August 1991. +.\" .SH REFERENCES +.\" .SS ESSENTIAL FILE FORMAT +.\" .TP +.\" .UR https://www.aelius.com/njh/wavemetatools/doc/riffmci.pdf +.\" Multimedia Programming Interface and Data Specifications 1.0 +.\" .UE +.\" The original definition of the +.\" .I RIFF +.\" container, the +.\" .I WAVE +.\" form, the original metadata facilites, and things like language, country and +.\" dialect enumerations. +.\" .TP +.\" .UR https://datatracker.ietf.org/doc/html/rfc2361 +.\" RFC 2361 +.\" .UE +.\" A large RFC compilation of all of the known (in 1998) audio encoding formats +.\" in use. 104 different codecs are documented with a name, the corresponding +.\" magic number, and a vendor contact name, phone number and address (no +.\" emails, strangely). Almost all of these are of historical interest only. +.\" .SS RF64/Extended WAVE Format +.\" +.\" .TP +.\" .UR https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.2088-1-201910-I!!PDF-E.pdf +.\" ITU Recommendation BS.2088-1-2019 +.\" .UE +.\" BS.2088 gives a detailed description of the internals of an RF64 file, +.\" .I ds64 +.\" structure and all formal requirements. It also defines the use of +.\" .IR , +.\" .IR , +.\" .IR , +.\" and +.\" .I +.\" metadata chunks for the carriage of Audio Definition Model metadata. +.\" .TP +.\" .UR https://tech.ebu.ch/docs/tech/tech3306.pdf +.\" EBU Tech 3306 "RF64: An Extended File Format for Audio Data" +.\" .UE +.\" Version 1 of Tech 3306 laid out the +.\" .I RF64 +.\" extended WAVE +.\" file format almost identically to +.\" .IR BS.2088 , +.\" Version 2 of the standard wholly adopted +.\" .IR BS.2088 .