diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 123e87a..1d9e7c6 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -17,11 +17,14 @@ instance of :class:`WaveInfoReader`. adm_metadata = info.adm ixml_metadata = info.ixml - + +WavInfoReader Class Documentation +-------------------------------------- .. module:: wavinfo :noindex: .. autoclass:: wavinfo.wave_reader.WavInfoReader :members: + :special-members: __init__ diff --git a/docs/source/scopes/bext.rst b/docs/source/scopes/bext.rst index faf17b9..2c80505 100644 --- a/docs/source/scopes/bext.rst +++ b/docs/source/scopes/bext.rst @@ -4,32 +4,43 @@ Broadcast WAV Extension Metadata Notes ----- -A WAV file produced to Broadcast-WAV specifications will have the broadcast metadata extension, -which includes a 256-character free text descrption, creating entity identifier (usually the -recording application or equipment), the date and time of recording and a time reference for -timecode synchronization. +A WAV file produced to Broadcast-WAV specifications will have the broadcast +metadata extension, which includes a 256-character free text descrption, +creating entity identifier (usually the recording application or equipment), +the date and time of recording and a time reference for timecode +synchronization. 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 :py:attr:`description`. -Here also the :py:attr:`originator_ref` +In this example (from a Sound Devices 702T) the bext metadata contains +scene/take slating 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 -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 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 + +.. note:: + All text fields in the Broadcast-WAV metadata structure are decoded by + default as flat ASCII. To override this and use a different encoding, pass + an string encoding name to the ``bext_encoding`` parameter of + :py:meth:`WavInfoReader()` + + Example ------- .. code:: python diff --git a/docs/source/scopes/cue.rst b/docs/source/scopes/cue.rst index 09d7ab3..96eed0e 100644 --- a/docs/source/scopes/cue.rst +++ b/docs/source/scopes/cue.rst @@ -9,6 +9,21 @@ in a wave file, and optionally give them a name and longer comment. Markers can also have an associated length, allowing ranges of times in a file to be marked. +String Encoding of Cue Metadata +""""""""""""""""""""""""""""""" + +Cue labels and notes will be decoded using the string encoding passed to +:py:meth:`WavInfoReader's` +``info_encoding=`` parameter, which by default is ``latin_1`` (ISO 8859-1). + +Text associated with ``ltxt`` time ranges may specify their own encoding in +the form of a Windows codepage number. `wavinfo` will attempt to use the +encoding specified. + +.. note:: + ``cset`` character set/locale metadata is not supported. If it is present + in the file it will be ignored by `wavinfo`. + Class Reference =============== diff --git a/docs/source/scopes/info.rst b/docs/source/scopes/info.rst index 7288fc6..fea8155 100644 --- a/docs/source/scopes/info.rst +++ b/docs/source/scopes/info.rst @@ -20,16 +20,16 @@ music library software. print("INFO Comment:", bullet.info.comment) -On Encodings -"""""""""""" -According to Microsoft, the original developers of the RIFF file and RIFF INFO -metadata, these fields are always to be interpreted as ISO Latin 1 characters, -and this is the default encoding used by `wavinfo` for these fields. You can -select a different encoding (like Shift-JIS) by passing an encoding name (as -would be used by `string.encode()`) to `WavInfoReader.__init__()`'s -`info_encoding=` parameter. - +String Encoding of Cue Metadata +""""""""""""""""""""""""""""""" +Info metadata fields will be decoded using the string encoding passed to +:py:meth:`WavInfoReader's` +``info_encoding=`` parameter, which by default is ``latin_1`` (ISO 8859-1). + +.. note:: + ``cset`` character set/locale metadata is not supported. If it is present + in the file it will be ignored by `wavinfo`. Class Reference --------------- diff --git a/wavinfo/wave_reader.py b/wavinfo/wave_reader.py index 85993e8..f856329 100644 --- a/wavinfo/wave_reader.py +++ b/wavinfo/wave_reader.py @@ -38,10 +38,8 @@ class WavInfoReader: file handle to an open file. :param info_encoding: - The text encoding of the INFO, LABL and other RIFF-defined metadata - fields. latin_1/ISO 8859-1/Win CP819 is the safest assumption for - this; chunks that define their own encoding explicitly (like LTXT) - will override this setting. + The text encoding of the ``INFO``, ``LABL`` and other RIFF-defined + metadata fields. :param bext_encoding: The text encoding to use when decoding the string