From b2323a126f1348a104d3e56d95caa71ff51fc6d9 Mon Sep 17 00:00:00 2001 From: Jamie Hardt Date: Wed, 23 Nov 2022 22:31:42 -0800 Subject: [PATCH] Docs --- docs/source/classes.rst | 10 +------- docs/source/metadata_scopes/adm.rst | 3 +++ docs/source/metadata_scopes/bext.rst | 17 ++++++++----- docs/source/quickstart.rst | 5 ++++ wavinfo/wave_adm_reader.py | 7 ++++-- wavinfo/wave_ixml_reader.py | 2 +- wavinfo/wave_reader.py | 37 +++++++++++++++++----------- 7 files changed, 49 insertions(+), 32 deletions(-) diff --git a/docs/source/classes.rst b/docs/source/classes.rst index 0a44820..605066b 100644 --- a/docs/source/classes.rst +++ b/docs/source/classes.rst @@ -1,18 +1,10 @@ Other wavinfo Classes -=============== +===================== -.. autoclass:: wavinfo.wave_reader.WavInfoReader - :members: - - .. automethod:: __init__ - - .. autoclass:: wavinfo.wave_reader.WavAudioFormat :members: .. autoclass:: wavinfo.wave_reader.WavDataDescriptor :members: - - diff --git a/docs/source/metadata_scopes/adm.rst b/docs/source/metadata_scopes/adm.rst index 11930dc..14ebd60 100644 --- a/docs/source/metadata_scopes/adm.rst +++ b/docs/source/metadata_scopes/adm.rst @@ -12,4 +12,7 @@ Class Reference .. module:: wavinfo .. autoclass:: wavinfo.wave_adm_reader.WavADMReader + :members: + +.. autoclass:: wavinfo.wave_adm_reader.ChannelEntry :members: \ No newline at end of file diff --git a/docs/source/metadata_scopes/bext.rst b/docs/source/metadata_scopes/bext.rst index 149da59..3d67ee7 100644 --- a/docs/source/metadata_scopes/bext.rst +++ b/docs/source/metadata_scopes/bext.rst @@ -9,20 +9,25 @@ which includes a 256-character free text descrption, creating entity identifier recording application or equipment), the date and time of recording and a time reference for timecode synchronization. -The `coding_history` is designed to contain a record of every conversion performed on the audio +The :py:attr:`coding_history` is designed to contain a record of every conversion performed on the audio file. In this example (from a Sound Devices 702T) the bext metadata contains scene/take slating -information in the `description`. Here also the `originator_ref` is a serial number conforming +information in the :py:attr:`description`. Here also the :py:attr:`originator_ref` is a serial number conforming to EBU Rec 99. -If the bext metadata conforms to EBU 3285 v1, it will contain the WAV's 32 or 64 byte SMPTE -330M UMID. The 32-byte version of the UMID is usually just a random number, while the 64-byte +If the bext metadata conforms to `EBU 3285 v1`_, it will contain the WAV's 32 or 64 byte `SMPTE +ST 330 UMID`_. The 32-byte version of the UMID is usually just a random number, while the 64-byte UMID will also have information on the recording date and time, recording equipment and entity, and geolocation data. -If the bext metadata conforms to EBU 3285 v2, it will hold precomputed program loudness values -as described by EBU Rec 128. +If the bext metadata conforms to `EBU 3285 v2`_, it will hold precomputed program loudness values +as described by `EBU Rec 128`_. + +.. _EBU 3285 v1: https://tech.ebu.ch/publications/tech3285s1 +.. _SMPTE ST 330 UMID: https://standards.globalspec.com/std/1396751/smpte-st-330 +.. _EBU 3285 v2: https://tech.ebu.ch/publications/tech3285s2 +.. _EBU Rec 128: https://tech.ebu.ch/publications/r128 .. code:: python diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 2607164..a3cad7e 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -10,3 +10,8 @@ ptulsconv Quickstart info = wavinfo.WavInfoReader(path) + + +.. autoclass:: wavinfo.wave_reader.WavInfoReader + :members: + diff --git a/wavinfo/wave_adm_reader.py b/wavinfo/wave_adm_reader.py index ce12c90..2621a21 100644 --- a/wavinfo/wave_adm_reader.py +++ b/wavinfo/wave_adm_reader.py @@ -47,8 +47,8 @@ class WavADMReader: Information about a track in the WAV file. :param index: index of audio track (indexed from zero) - :returns: a dictionary with content_name, object_name, pack_format_name, pack_type, - channel_format_name + :returns: a dictionary with *content_name*, *object_name*, *pack_format_name*, *pack_type*, + *channel_format_name* """ channel_info = next((x for x in self.channel_uids if x.track_index == index + 1), None) @@ -86,4 +86,7 @@ class WavADMReader: return ret_dict def to_dict(self): + """ + Get ADM metadata as a dictionary. + """ return dict(channel_entries=list(map(lambda z: z._asdict(), self.channel_uids))) \ No newline at end of file diff --git a/wavinfo/wave_ixml_reader.py b/wavinfo/wave_ixml_reader.py index 7f290a5..7e2e431 100644 --- a/wavinfo/wave_ixml_reader.py +++ b/wavinfo/wave_ixml_reader.py @@ -38,7 +38,7 @@ class WavIXMLFormat: def track_list(self): """ A description of each track. - :return: An Iterator + :returns: An Iterator """ for track in self.parsed.find("./TRACK_LIST").iter(): if track.tag == 'TRACK': diff --git a/wavinfo/wave_reader.py b/wavinfo/wave_reader.py index 59eeae0..2335cb5 100644 --- a/wavinfo/wave_reader.py +++ b/wavinfo/wave_reader.py @@ -3,6 +3,8 @@ import struct import os from collections import namedtuple +from typing import Optional + import pathlib from .riff_parser import parse_chunk, ChunkDescriptor, ListChunkDescriptor @@ -22,6 +24,8 @@ WavAudioFormat = namedtuple('WavAudioFormat', class WavInfoReader: """ Parse a WAV audio file for metadata. + + """ def __init__(self, path, info_encoding='latin_1', bext_encoding='ascii'): @@ -55,10 +59,24 @@ class WavInfoReader: absolute_path = os.path.abspath(path) #: `file://` url for the file. - self.url = pathlib.Path(absolute_path).as_uri() + self.url: pathlib.Path = pathlib.Path(absolute_path).as_uri() - # for __repr__() self.path = absolute_path + + self.fmt :Optional[WavAudioFormat] = None + ":class:`wavinfo.wave_reader.WavAudioFormat`" + + self.bext :Optional[WavBextReader] = None + ":class:`wavinfo.wave_bext_reader.WavBextReader` with Broadcast-WAV metadata" + + self.ixml :Optional[WavIXMLFormat] = None + ":class:`wavinfo.wave_ixml_reader.WavIXMLFormat` with iXML metadata" + + self.adm :Optional[WavADMReader]= None + ":class:`wavinfo.wave_axml_reader.WavADMReader` with ADM metadata" + + self.info :Optional[WavInfoChunkReader]= None + ":class:`wavinfo.wave_info_reader.WavInfoChunkReader` with RIFF INFO metadata" with open(path, 'rb') as f: self.get_wav_info(f) @@ -69,19 +87,10 @@ class WavInfoReader: self.main_list = chunks.children wavfile.seek(0) - #: :class:`wavinfo.wave_reader.WavAudioFormat` self.fmt = self._get_format(wavfile) - - #: :class:`wavinfo.wave_bext_reader.WavBextReader` with Broadcast-WAV metadata self.bext = self._get_bext(wavfile, encoding=self.bext_encoding) - - #: :class:`wavinfo.wave_ixml_reader.WavIXMLFormat` with iXML metadata self.ixml = self._get_ixml(wavfile) - - #: :class:`wavinfo.wave_axml_reader.WavAxmlReader` with ADM metadata self.adm = self._get_adm(wavfile) - - #: :class:`wavinfo.wave_info_reader.WavInfoChunkReader` with RIFF INFO metadata self.info = self._get_info(wavfile, encoding=self.info_encoding) self.data = self._describe_data() @@ -149,9 +158,9 @@ class WavInfoReader: """ Walk all of the available metadata fields. - :yields: a string, the :scope: of the metadatum, the string :name: of the - metadata field, and the value. - + :yields: tuples of the *scope*, *key*, and *value* of + each metadatum. The *scope* value will be one of + "fmt", "data", "ixml", "bext", "info" or "adm". """