demodocus
=========

**demodocus** is Python CLI program to quickly check synchronization
maps.

-  Version: 1.0.0
-  Date: 2015-12-12
-  Developer: `Alberto Pettarin <http://www.albertopettarin.it/>`__
-  License: the MIT License (MIT)
-  Contact: `click here <http://www.albertopettarin.it/contact.html>`__

Installation
------------

Using pip
~~~~~~~~~

1. Open a console and type:

   .. code:: bash

       $ [sudo] pip install demodocus

2. That's it! Just run without arguments (or with ``-h`` or ``--help``)
   to get the manual:

   .. code:: bash

       $ demodocus

Make sure to have ``ffmpeg`` installed and available on your ``PATH``
environment variable, see below.

From source code
~~~~~~~~~~~~~~~~

1. Get the source code:

   -  clone this repo with ``git``:

      .. code:: bash

          $ git clone https://github.com/pettarin/demodocus.git

   -  or download the `latest
      release <https://github.com/pettarin/demodocus/releases>`__ and
      uncompress it somewhere,
   -  or download the `current master
      ZIP <https://github.com/pettarin/demodocus/archive/master.zip>`__
      and uncompress it somewhere.

2. Open a console and enter the ``demodocus`` (cloned) directory:

   .. code:: bash

       $ cd /path/to/demodocus

3. Install the requirements:

   .. code:: bash

       $ [sudo] pip -r requirements.txt

4. That's it! Just run without arguments (or with ``-h`` or ``--help``)
   to get the manual:

   .. code:: bash

       $ python -m demodocus

Make sure to have ``ffmpeg`` installed and available on your ``PATH``
environment variable, see below.

Dependencies
~~~~~~~~~~~~

-  Python, version 2.7.x or 3.4.x (or above)

-  ``ffmpeg``: download it from https://www.ffmpeg.org/ or install it
   with your packet manager

-  ``pyaudio`` : install it via ``pip``:

   .. code:: bash

       $ [sudo] pip install pyaudio

   (if a compilation error appears, check that you have the PortAudio
   1.9 headers available: in Debian, they are provided by the
   ``portaudio19-dev`` package)

Usage
-----

::

    usage: 
      $ demodocus -h
      $ demodocus -a AUDIO -s SYNCMAP [OPTIONS]

    description:
      Run an interactive CLI tool to verify that SYNCMAP has a good alignment against AUDIO.
      The sync map file can be in JSON or SSV/SSVH format (auto-detected).

    optional arguments:
      -h, --help            show this help message and exit
      -a AUDIO, --audio AUDIO
                            path to the audio file
      -c, --continuous      keep going (default: False)
      -d DURATION, --duration DURATION
                            play audio for max DURATION seconds (default: 2)
      -i INCREMENT, --increment INCREMENT
                            play audio every INCREMENT fragments (default: 1)
      -s SYNCMAP, --syncmap SYNCMAP
                            path to the sync map file
      -v, --version         print version and exit
      -w WAIT, --wait WAIT  wait WAIT seconds before playing the next fragment
                            (default: 0)

    examples:

      $ demodocus -a audio.mp3 -s syncmap.json
        Check audio.mp3 against syncmap.json with default parameters (2 seconds, all fragments)

      $ demodocus -a audio.mp3 -s syncmap.ssv
        As above, but the sync map file has SSV format

      $ demodocus -a audio.mp3 -s syncmap.json -d 1
        Play each fragment for max 1 second

      $ demodocus -a audio.mp3 -s syncmap.json -d 3 -i 5
        Play every 5 fragments, for max 3 seconds each

      $ demodocus -a audio.mp3 -s syncmap.json -d 3 -i 5 -w 0.5
        Pause for 0.5 seconds before playing next fragment

      $ demodocus -a audio.mp3 -s syncmap.json -c -i 5 -d 1.5 -w 0.5
        Play every 5 fragments, 1.5 seconds each, continuously, pausing for 0.5 seconds

License
-------

**demodocus** is released under the MIT License.

Limitations and Missing Features
--------------------------------

-  The input file must be converted to WAVE before running: slow for
   very large input files
-  Dependency from ``ffmpeg``, called via ``subprocess`` to convert the
   input file to WAVE
-  Dependency from ``pyaudio``, which in turns depends on ``PortAudio``
-  No tests
-  No documentation
