Skip to content

Commit

Permalink
Add more documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@NumerousHats
NumerousHats committed Jul 22, 2019
1 parent dc14895 commit 683fabf
Show file tree
Hide file tree
Showing 6 changed files with 305 additions and 59 deletions.
155 changes: 155 additions & 0 deletions docs/configuration.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
Configuration
===============

Program configuration is stored as a `JSON <https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects
/JSON>`_ file named ``autobwfconfig.json`` in a directory appropriate to your operating system. If the file does not
exist, then a "starter" file will be created for you.

This file should be edited using the text editing program of your choice in order to reflect your repository's usage.
In particular, you can customize the values in all of the dropdown menus, set the boilerplate copyright
texts, and save the models and serial numbers of your hardware for constructing the BWF CodingHistory element.


Originator and repository information
----------------------------------------

- Set the pre-filled value for the BWF Originator element::

"originator": "Apocryphal St. U. Archives"


- Set the value of the RIFF IARL element::

"iarl": "US, Apocryphal State University Archives and Special Colletions"

- Set the repository code used to construct the BWF OriginatorRef element::

"repocode": "ApoSU"

.. _program_behavior:

Program behavior
-----------------

- Control whether ``bwfmetaedit`` is sent the ``--accept-nopadding`` flag (no if 0, yes otherwise)::

"accept-nopadding": 1

- Specify the filename format (see below for full usage details)::

"filenameRegex": ".*_([0-9-]+_[A-Z]{2}\\\d+)_\\\d+_([a-zA-Z]+)_(\\\d+)\\\.wav"

- Control how the file use portion of the file name is translated into a file use statement in the BWF Description::

"fileuse": {
"pres": "Preservation Master",
"presInt": "Preservation Master-Intermediate",
"prod": "Production Master"
}

Combo box elements
---------------------

The prefilled values of the autoBWF combo box GUI elements (ISFT, ITCH, ISRC, Copyright owner) are controlled by list
value associated with the appropriate key::

"isft": [
"Audacity 2.0.3.0",
"Audacity 2.3.2"
],
"technician": [
"Doe, John",
"Doe, Jane"
],
"source": [
"Billy Bob Apocryphal papers",
"Apocryphal University Radio records"
],
"owner": [
"Apocryphal State University",
"Big Donor"
]

If you want a combo box to be empty be default but still have a set of preconfigured choices in the dropdown, then
make the first element of the list an empty string::

"technician": [
"",
"Doe, John",
"Doe, Jane"
]


Copyright boilerplate
----------------------

The copyright dropdown menu and associated texts are controled by the ``copyright`` key::

"copyright": {
"list": ["Generic", "CC-BY-SA"],
"Generic": "Publication and other forms of distribution (including online sharing and streaming) may be restricted. For details, contact the Apocryphal State University Archives.",
"CC-BY-SA": "This content is copyright by the Apocryphal State University, and is licenced under Creative Commons BY-SA. See https://creativecommons.org/licenses/by-sa/4.0/ for details."
}

Within it is the ``list`` key, the corresponding value of which is a list of user-friendly names for the various
copyright choices in the form that they should appear in the dropdown menu. That should be followed by key-value pairs
corresponding to each of those user-friendly names and the corresponding boilerplate text that should be filled in
the text field. For example, we can add a "public domain" menu choice as follows::

"copyright": {
"list": ["Generic", "CC-BY-SA", "Public domain"],
"Generic": "Publication and other forms of distribution (including online sharing and streaming) may be restricted. For details, contact the Apocryphal State University Archives.",
"CC-BY-SA": "This content is copyright by the Apocryphal State University, and is licenced under Creative Commons BY-SA. See https://creativecommons.org/licenses/by-sa/4.0/ for details."
"Public domain": "This content has been placed into the public domain."
}

CodingHistory constructor menus
--------------------------------

autoBWF constructs the CodingHistory text based on user selections in the dropdown menus to the right of the text
box. The contents of those menus is controlled by the following JSON elements::

"deck": {
"list": ["Studer", "Realistic"],
"Studer": "Studer A810 SN:11223344",
"Realistic": "Realistic 909A SN:1234321"
},

"adc": {
"list": ["Lynx"],
"Lynx": "Lynx Aurora 16 SN:897969"
},

"software": {
"list": ["Audacity - Mac", "Audacity - Linux"],
"Audacity - Mac": "Audacity 2.0.3.0 (Mac)",
"Audacity - Linux": "Audacity x.x.x. (Linux Ubuntu)"
},


"media": [
"1/4 inch open reel",
"cassette"
],

"speed": [
"",
"7.5 ips",
"3.25 ips"
],

"eq": [
"",
"Dolby B",
"Dolby C"
],

"type": [
"",
"CrO2",
"Metal"
],

Some of these elements have a "list" key similar to the copyright dropdown menu configuration ("deck", "adc",
"software"), while for the remainder the text in the dropdown menu is the same as the text inserted into the
CodingHistory (similar to the combo box configuration).
31 changes: 0 additions & 31 deletions docs/details.rst
View file

This file was deleted.

23 changes: 17 additions & 6 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,18 @@
autoBWF
===================================
The purpose of ``autoBWF`` is to provide an Python/PyQt5 GUI for embedding internal metadata in WAVE audio files using the `Broadcast Wave <https://en.wikipedia.org/wiki/Broadcast_Wave_Format>`_ standard, FADGI `BWFMetaEdit <https://mediaarea.net/BWFMetaEdit>`_, and `XMP <https://en.wikipedia.org/wiki/Extensible_Metadata_Platform>`_.
The purpose of ``autoBWF`` is to provide an Python/PyQt5 GUI for embedding internal metadata in WAVE audio files
using the `Broadcast Wave <https://en.wikipedia.org/wiki/Broadcast_Wave_Format>`_ standard, FADGI
`BWFMetaEdit <https://mediaarea.net/BWFMetaEdit>`_, and
`XMP <https://en.wikipedia.org/wiki/Extensible_Metadata_Platform>`_.

Unlike the existing BWFMetaEdit GUI, autoBWF is extremely opinionated and will automatically generate metadata content based on file naming conventions, system metadata, and pre-configured repository defaults. In addition, it can copy metadata fields from a template file to avoid having to enter the same information multiple times for derivative files of the same physical instantiation.
Unlike the existing BWFMetaEdit GUI, autoBWF is extremely opinionated and will automatically generate metadata
content based on file naming conventions, system metadata, and pre-configured repository defaults. In addition, it
can copy metadata fields from a template file to avoid having to enter the same information multiple times
for derivative files of the same physical instantiation.

Also included are two command line programs (``autosplice`` and ``autolame``) which simplify the creation of derivative files.
Also included are two command line programs (``autosplice`` and ``autolame``) which simplify the creation
of derivative files.

Contents
++++++++++++
Expand All @@ -18,11 +25,15 @@ Contents

installation
usage
details
configuration
splicelame

Known issues
++++++++++++++

* Reading of XMP data causes a temp file to be created and deleted in the same directory as the WAVE file. This may cause a change to the modification time for the directory, which could cause a problem for some digital preservation schemes.
* ``autoBWF`` strives to write valid XMP, but when reading Wave files it makes significant assumptions about the structure of the XMP XML beyond those mandated by the XMP standard. Therefore, it is capable of reliably reading only XMP generated by ``autoBWF`` itself, and metadata written by other software may not be correctly parsed.
* Reading of XMP data causes a temp file to be created and deleted in the same directory as the WAVE file. This
may cause a change to the modification time for the directory, which could cause a problem for some digital
preservation schemes.
* ``autoBWF`` strives to write valid XMP, but when reading Wave files it makes significant assumptions about
the structure of the XMP XML beyond those mandated by the XMP standard. Therefore, it is capable of reliably
reading only XMP generated by ``autoBWF`` itself, and metadata written by other software may not be correctly parsed.
40 changes: 32 additions & 8 deletions docs/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,43 @@ Prerequisites
Python 3
------------

This code requires Python 3.6 or later. If you are running on Linux or Mac OS, then it is almost certainly already installled. If you are running on Widows, you can install Python using instructions that can be found on any number of web sites (such as `this one <https://www.digitalocean.com/community/tutorials/how-to-install-python-3-and-set-up-a-local-programming-environment-on-windows-10>`_).
This code requires Python 3.6 or later. If you are running on Linux or Mac OS,
then it is almost certainly already installled. If you are running on Widows,
you can install Python using instructions that can be found on any number of web
sites (such as `this one
<https://www.digitalocean.com/community/tutorials/how-to-install-
python-3-and-set-up-a-local-programming-environment-on-windows-10>`_).

You may wish to configure a `virtual environment <https://docs.python-guide.org/dev/virtualenvs/>`_ within which to install and run ``autoBWF``.
You may wish to configure a `virtual environment
<https://docs.python-guide.org/dev/virtualenvs/>`_ within which to install and
run ``autoBWF``.

bwfmetaedit
----------------------------
Download the and run the installer for the `BWFMetaEdit <https://mediaarea.net/BWFMetaEdit>`_ CLI (Command Line Interface) appropriate to your operating system from `mediaarea.net <https://mediaarea.net/BWFMetaEdit/Download>`_. Note that simply having the BWFMetaEdit GUI installed is not sufficient.
Download the and run the installer for the `BWFMetaEdit
<https://mediaarea.net/BWFMetaEdit>`_ CLI (Command Line Interface) appropriate
to your operating system from `mediaarea.net <https://mediaarea
.net/BWFMetaEdit/Download>`_. Note that simply having the BWFMetaEdit GUI
installed is not sufficient.

``autoBWF`` has been tested with ``bwfmetaedit`` v1.3.3 and v1.3.8. Note that earlier versions of ``bwfmetaedit`` have a bug that introduces spurious characters at the end of the ``CodingHistory`` element. This bug has been confirmed to exist in v1.3.1.1, and it may affect other versions prior to v1.3.3.
``autoBWF`` has been tested with ``bwfmetaedit`` v1.3.3 and v1.3.8. Note that
earlier versions of ``bwfmetaedit`` have a bug that introduces spurious characters
at the end of the ``CodingHistory`` element. This bug has been confirmed to exist
in v1.3.1.1, and it may affect other versions prior to v1.3.3.

Optional software
----------------------

In order to run ``autolame`` and ``autosplice``, you will also need to install `lame <http://lame.sourceforge.net/>`_ (for ``autolame``) and `SoX <http://sox.sourceforge.net/>`_ v14.4.2 (for ``autosplice``).
In order to run ``autolame`` and ``autosplice``, you will also need to install
`lame <http://lame.sourceforge.net/>`_ (for ``autolame``) and `SoX <http://sox
.sourceforge.net/>`_ v14.4.2 (for ``autosplice``).

Note that some LINUX package repositories (e.g. Ubuntu 16.04) have an earlier version of ``SoX`` that seems to have problems with time specifications, so you may need to install from source. If you are doing so on Ubuntu, you may need to run ``sudo ldconfig`` after installation if you get a ``sox: error while loading shared libraries: libsox.so.3: cannot open shared object file: No such file or directory`` error.
Note that some LINUX package repositories (e.g. Ubuntu 16.04) have an earlier
version of ``SoX`` that seems to have problems with time specifications, so you
may need to install from source. If you are doing so on Ubuntu, you may need to
run ``sudo ldconfig`` after installation if you get a ``sox: error while loading
shared libraries: libsox.so.3: cannot open shared object file: No such file or
directory`` error.

Installing autoBWF
+++++++++++++++++++++++++
Expand All @@ -31,8 +52,11 @@ The latest release of ``autoBWF`` is available on PyPI and can be installed usin

pip3 install autoBWF

The "bleeding edge" version is in the master branch `on github <https://github.com/Ukrainian-History/autoBWF>`_, and can be installed by cloning the repository and installing the local code with ``pip3``, or by running ::
The "bleeding edge" version is in the master branch `on github <https://github
.com/Ukrainian-History/autoBWF>`_, and can be installed by cloning the repository
and installing the local code with ``pip3``, or by running ::

pip3 install git+git://github.com/Ukrainian-History/autoBWF.git#egg=autoBWF

The master branch contains functional code - all development work that is likely to result in a broken state is done on feature branches.
The master branch contains functional code - all development work that is likely
to result in a broken state is done on feature branches.
36 changes: 28 additions & 8 deletions docs/splicelame.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
autosplice and autolame
Autosplice and autolame
===========================

autosplice
Expand All @@ -8,15 +8,27 @@ Usage::

autosplice <EDL file>

where `<EDL file>` is a text file that is vaguely reminiscent of an `edit decision list <https://en.wikipedia.org/wiki/Edit_decision_list>`_.
where `<EDL file>` is a text file that is vaguely reminiscent of an `edit
decision list <https://en.wikipedia.org/wiki/Edit_decision_list>`_.

Specifically, the EDL file consists of any number of lines of the form ::

filename.wav <in-time> <out-time>

which may also optionally contain `fade <in duration> <out duration>` and/or `pad <start padding> <end padding>`. This will append the audio in `filename.wav` from time `<in-time>` to time `<out-time>` (relative to start of the file). All times and durations are in SoX time specification syntax (see the Sox man page for details). The optional `fade` and `pad` parameters add fade in and/or fade out (both values are required: set either to zero if no fade is desired), or padding with silence at beginning and/or end (both values are required: set either to zero if no padding is desired). Padding is added before fade in and after fade out.

The input file must end with a line containing only a filename, and optionally the text `contrast <value>`, but no in or out times. This specifies the name of the output file, as well as any optional SoX "contrast" (a form of audio dynamic range compression).
which may also optionally contain `fade <in duration> <out duration>` and/or
`pad <start padding> <end padding>`. This will append the audio in
`filename.wav` from time `<in-time>` to time `<out-time>` (relative to start
of the file). All times and durations are in SoX time specification syntax
(see the Sox man page for details). The optional `fade` and `pad` parameters add
fade in and/or fade out (both values are required: set either to zero if no fade
is desired), or padding with silence at beginning and/or end (both values are
required: set either to zero if no padding is desired). Padding is added before
fade in and after fade out.

The input file must end with a line containing only a filename, and optionally
the text `contrast <value>`, but no in or out times. This specifies the name of
the output file, as well as any optional SoX "contrast" (a form of audio dynamic
range compression).

Example of an EDL input file::

Expand All @@ -29,7 +41,12 @@ Example of an EDL input file::
Security note
+++++++++++++++++

``autosplice`` calls ``sox`` using unsanitized strings passed to the Python ``subprocess.call()`` function with the ``shell=True`` argument set. This is a theorectical security risk, as a maliciously-crafted EDL file obtained from an untrusted source could result in a shell injection attack. It is mitigated by the fact that such a malicious file should be easily recognizable by simple visual inspection.
``autosplice`` calls ``sox`` using unsanitized strings passed to the Python
``subprocess.call()`` function with the ``shell=True`` argument. This is a
theorectical security risk, as a maliciously-crafted EDL file obtained from an
untrusted source could result in a shell injection attack. It is mitigated by the
fact that such a malicious file should be easily recognizable by simple visual
inspection.

autolame
--------------
Expand All @@ -38,8 +55,11 @@ Usage::

autolame [-h] [-o OUTFILE] [--vbr-level VBR_LEVEL] infile [infile ...]

Each `<infile>` will be converted to mp3 and the result will be saved to the same file name with the extension changed to mp3. Multiple <infile>s can be given, or generated using a shell glob (e.g. `*.wav`)
Each `<infile>` will be converted to mp3 and the result will be saved to the same
file name with the extension changed to mp3. Multiple <infile>s can be given, or
generated using a shell glob (e.g. `*.wav`)

An output file name can be specified using the ``-o`` option, but in that case only one input file is allowed.
An output file name can be specified using the ``-o`` option, but in that case
only one input file is allowed.

The default VBR level is currently 7.

0 comments on commit 683fabf

Please sign in to comment.