Begin setup of sphinx documentation

.gitignore

@@ -12,3 +12,6 @@ Pipfile
 Pipfile.lock
 build
 dist
+
+docs/_build/*
+coverage.xml

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,55 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'autoBWF'
+copyright = '2019, Michael Andrec/UHEC'
+author = 'Michael Andrec/UHEC'
+
+# The full version, including alpha/beta/rc tags
+release = '3.3.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/details.rst

@@ -0,0 +1,31 @@
+Configuration
+===========================
+
+
+Program configuration is stored as a JSON file in a directory appropriate to your operating system (e.g. `~/.local/share/autoBWF` on Linux or `/Users/yourname/Library/Application Support/autoBWF` on MacOS).
+
+If the file does not exist, then a "starter" ``autobwfconfig.json`` will be created for you. You should edit this file to customize the values in the dropdown menus and other program behavior to the needs of your repository. In addition, the config file includes the model, serial number, and software version strings that go into constructing the CodingHistory element and copyright boilerplate texts.
+
+The structure of the config file
+++++++++++++++++++++++++++++++++++++
+
+The ``--accept-nopadding`` flag is sent to ``bwfmetaedit`` by default, but that behavior can also be changed in the configuration file.
+
+**[TODO: explain in detail how the JSON works]**
+
+How does autoBWF generate metadata?
+++++++++++++++++++++++++++++++++++++
+
+From filenames
+-----------------
+The code assumes that filenames follow a convention similar to that used by the Indiana University Archives of Traditional Music as described in the `"Sound Directions" report <http://www.dlib.indiana.edu/projects/sounddirections/papersPresent/index.shtml>`_. If the naming convention at your archives is different, then you may be able to make things work by modifying the regex string in config.json, or more substantial customization to the Python code may need to be made.
+
+**[TODO: explain what regex capture groups are required]**
+
+If the program cannot parse the filename, then it will display a warning, use the OS file creation date and time to generate OriginationDate, OriginationTime, and OriginatorRef, and will leave Description blank.
+
+
+From operating system metadata
+--------------------------------
+
+The values of Description, Originator, OriginationDate, OriginationTime, and OriginatorRef are prefilled based on parsing the filename and using file creation date and times obtained from OS metadata together with default values in ``autobwfconfig.json``. If there is a conflict between the OS metadata date and that in the filename, then the program will display a warning and will allow you to choose which one you want to use.

docs/index.rst

@@ -0,0 +1,28 @@
+.. autoBWF documentation master file, created by
+   sphinx-quickstart on Thu Jul 18 14:34:48 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+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>`_.
+
+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.
+
+Contents
+++++++++++++
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   usage
+   details
+   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.

docs/installation.rst

@@ -0,0 +1,38 @@
+Installation
+================
+
+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>`_).
+
+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.
+
+``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``).
+
+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
++++++++++++++++++++++++++
+
+The latest release of ``autoBWF`` is available on PyPI and can be installed using ::
+
+    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 ::
+
+    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.

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/splicelame.rst

@@ -0,0 +1,45 @@
+autosplice and autolame
+===========================
+
+autosplice
+------------
+
+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>`_.
+
+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).
+
+Example of an EDL input file::
+
+    file1.wav 02:40+54392s 03:03+26995s fade 0 5
+    file1.wav 03:31+26995s 04:35+08823s fade 0 20 pad 1.5 2.5
+    file2.wav 14:12+26995s 15:02+08823s fade 15 5
+    file3.wav 0 5
+    output_file.wav
+
+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.
+
+autolame
+--------------
+
+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`)
+
+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.

docs/usage.rst

@@ -0,0 +1,22 @@
+Usage
+=======
+
+Simply type ::
+
+    autoBWF
+
+on the command line, and use the GUI "Open" menu item to load your WAVE file.
+
+Alternatively, you can avoid the "Open" dialog by specifying the target file and (optional) template file on the command line::
+
+    autoBWF <target_filename> [-t <template_filename>]
+
+``autoBWF`` will prepopulate the Description, Originator, OriginationDate, OriginationTime, and OriginatorRef GUI elements with reasonable guesses as described below.
+
+If *target_filename* already contains BWF metadata, then those values will appear in the GUI in grey italic text. If the user edits those fields, the text color will change to red as a warning that "Save metadata" will cause those the values will be overwritten in the target file. **This cannot be undone!**
+
+The CodingHistory text is generated automatically based on the selections made in the drop-downs to the right of the text box and the values in the configuration file (see below). You can also edit the text manually, but be aware that using the drop-down menus will undo any manual edits that you have made. Similarly, the Copyright text is replaced with the boilerplate corresponding to the dropdown menu selection. The same caveat regarding manual editing holds here as well.
+
+Loading a template file (either using the "Load Template" button or using the ``-t`` command line argument) will prepopulate the contents of the Title, Technician, Source, Copyright, Coding History, and any XMP text fields with the corresponding metadata contained in *template_filename*. These can always be edited before saving the metadata to the target file. Note that if the target file already has metadata in the same fields as the template, then this could result in the overwriting of data. `This issue <https://github.com/Ukrainian-History/autoBWF/issues/2>`_ will be resolved in a future version.
+
+It is strongly recommended that you work with test files and confirm (using BWFMetaEdit and/or a metadata viewer like ``exiftool``) that ``autoBWF`` is behaving the way that you expect before working with master files.