amine@432: Command-line guide
amine@432: ==================
amine@379: 
amine@432: ``auditok`` can also be used from the command line. For information
amine@432: about available parameters and descriptions, type:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok -h
amine@379: 
amine@432: Below, we provide several examples covering the most common use cases.
amine@379: 
amine@379: 
amine@441: Real-Time audio acquisition and event detection
amine@441: -----------------------------------------------
amine@379: 
amine@432: To try ``auditok`` from the command line with your own voice, you’ll need to
amine@432: either install `pyaudio <https://people.csail.mit.edu/hubert/pyaudio>`_ so
amine@432: that ``auditok`` can read directly from the microphone, or record audio with
amine@432: an external program (e.g., `sox`) and redirect its output to ``auditok``.
amine@379: 
amine@432: To read data directly from the microphone and use default parameters for audio
amine@432: data and tokenization, simply type:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok
amine@379: 
amine@432: This will print the **id**, **start time**, and **end time** of each detected
amine@432: audio event. As mentioned above, no additional arguments were passed in the
amine@432: previous command, so ``auditok`` will use its default values. The most important
amine@432: arguments are:
amine@379: 
amine@379: 
amine@432: - ``-n``, ``--min-duration``: minimum duration of a valid audio event in seconds, default: 0.2
amine@432: - ``-m``, ``--max-duration``: maximum duration of a valid audio event in seconds, default: 5
amine@432: - ``-s``, ``--max-silence``: maximum duration of a continuous silence within a valid audio event in seconds, default: 0.3
amine@432: - ``-e``, ``--energy-threshold``: energy threshold for detection, default: 50
amine@379: 
amine@379: 
amine@379: Read audio data with an external program
amine@379: ----------------------------------------
amine@432: You can use an external program, such as `sox` (``sudo apt-get install sox``),
amine@432: to record audio data in real-time, redirect it, and have `auditok` read the data
amine@432: from standard input:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     rec -q -t raw -r 16000 -c 1 -b 16 -e signed - | auditok - -r 16000 -w 2 -c 1
amine@379: 
amine@432: Note that when reading data from standard input, the same audio parameters must
amine@432: be set for both `sox` (or any other data generation/acquisition tool) and ``auditok``.
amine@432: The following table provides a summary of the audio parameters:
amine@379: 
amine@379: +-----------------+------------+------------------+-----------------------+
amine@379: | Audio parameter | sox option | `auditok` option | `auditok` default     |
amine@379: +=================+============+==================+=======================+
amine@379: | Sampling rate   | -r         | -r               |                 16000 |
amine@379: +-----------------+------------+------------------+-----------------------+
amine@379: | Sample width    | -b (bits)  | -w (bytes)       |                     2 |
amine@379: +-----------------+------------+------------------+-----------------------+
amine@379: | Channels        | -c         | -c               |                     1 |
amine@379: +-----------------+------------+------------------+-----------------------+
amine@379: | Encoding        | -e         | NA               | always a signed int   |
amine@379: +-----------------+------------+------------------+-----------------------+
amine@379: 
amine@432: Based on the table, the previous command can be run with the default parameters as:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@432:     rec -q -t raw -r 16000 -c 1 -b 16 -e signed - | auditok -
amine@432: 
amine@379: 
amine@379: Play back audio detections
amine@379: --------------------------
amine@379: 
amine@432: Use the ``-E`` (or ``--echo``) option :
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok -E
amine@379:     # or
amine@379:     rec -q -t raw -r 16000 -c 1 -b 16 -e signed - | auditok - -E
amine@379: 
amine@379: 
amine@379: Using ``-E`` requires `pyaudio`, if it's not installed you can use the ``-C``
amine@379: (used to run an external command with detected audio event as argument):
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     rec -q -t raw -r 16000 -c 1 -b 16 -e signed - | auditok - -C "play -q {file}"
amine@379: 
amine@379: Using the ``-C`` option, ``auditok`` will save a detected event to a temporary wav
amine@379: file, fill the ``{file}`` placeholder with the temporary name and run the
amine@379: command. In the above example we used ``-C`` to play audio data with an external
amine@379: program but you can use it to run any other command.
amine@379: 
amine@379: 
amine@441: Output detection details
amine@441: ------------------------
amine@379: 
amine@432: By default, ``auditok`` outputs the **id**, **start**, and **end** times for each
amine@432: detected audio event. The start and end values indicate the beginning and end of
amine@432: the event within the input stream (file or microphone) in seconds. Below is an
amine@432: example of the output in the default format:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     1 1.160 2.390
amine@379:     2 3.420 4.330
amine@379:     3 5.010 5.720
amine@379:     4 7.230 7.800
amine@379: 
amine@379: The format of the output is controlled by the ``--printf`` option. Alongside
amine@379: ``{id}``, ``{start}`` and ``{end}`` placeholders, you can use ``{duration}`` and
amine@379: ``{timestamp}`` (system timestamp of detected event) placeholders.
amine@379: 
amine@379: Using the following format for example:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok audio.wav  --printf "{id}: [{timestamp}] start:{start}, end:{end}, dur: {duration}"
amine@379: 
amine@432: the output will look like:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     1: [2021/02/17 20:16:02] start:1.160, end:2.390, dur: 1.230
amine@379:     2: [2021/02/17 20:16:04] start:3.420, end:4.330, dur: 0.910
amine@379:     3: [2021/02/17 20:16:06] start:5.010, end:5.720, dur: 0.710
amine@379:     4: [2021/02/17 20:16:08] start:7.230, end:7.800, dur: 0.570
amine@379: 
amine@379: 
amine@379: The format of ``{timestamp}`` is controlled by ``--timestamp-format`` (default:
amine@379: `"%Y/%m/%d %H:%M:%S"`) whereas that of ``{start}``, ``{end}`` and ``{duration}``
amine@379: by ``--time-format`` (default: `%S`, absolute number of seconds). A more detailed
amine@379: format with ``--time-format`` using `%h` (hours), `%m` (minutes), `%s` (seconds)
amine@379: and `%i` (milliseconds) directives is possible (e.g., "%h:%m:%s.%i).
amine@379: 
amine@379: To completely disable printing detection information use ``-q``.
amine@379: 
amine@441: 
amine@379: Save detections
amine@379: ---------------
amine@379: 
amine@379: You can save audio events to disk as they're detected using ``-o`` or
amine@441: ``--save-detections-as`` followed by a file name with placeholders. To create
amine@441: a uniq file name for each event, you can use ``{id}``, ``{start}``, ``{end}``
amine@441: and ``{duration}`` placeholders as in this example:
amine@379: 
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok --save-detections-as "{id}_{start}_{end}.wav"
amine@379: 
amine@432: When using ``{start}``, ``{end}``, and ``{duration}`` placeholders, it is
amine@432: recommended to limit the number of decimal places for these values to 3. You
amine@432: can do this with a format like:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok -o "{id}_{start:.3f}_{end:.3f}.wav"
amine@379: 
amine@379: 
amine@441: Save the full audio stream
amine@441: --------------------------
amine@379: 
amine@432: When reading audio data from the microphone, you may want to save it to disk.
amine@432: To do this, use the ``-O`` or ``--save-stream`` option:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@432:     auditok --save-stream output.wav
amine@379: 
amine@432: Note that this will work even if you read data from a file on disk.
amine@379: 
amine@379: 
amine@437: Join detected audio events, inserting a silence between them
amine@437: ------------------------------------------------------------
amine@432: 
amine@441: Sometimes, you may want to detect audio events and create a new file containing
amine@441: these events with pauses of a specific duration between them. This is useful if
amine@441: you wish to preserve your original audio data while adjusting the length of pauses
amine@441: (either shortening or extending them).
amine@432: 
amine@437: To achieve this, use the ``-j`` or ``--join-detections`` option together
amine@432: with the ``-O`` / ``--save-stream`` option. In the example below, we
amine@441: read data from ``input.wav`` and save audio events to ``output.wav``, adding
amine@432: 1-second pauses between them:
amine@432: 
amine@432: .. code:: bash
amine@432: 
amine@432:     auditok input.wav --join-detections 1 -O output.wav
amine@432: 
amine@441: 
amine@379: Plot detections
amine@379: ---------------
amine@379: 
amine@379: Audio signal and detections can be plotted using the ``-p`` or ``--plot`` option.
amine@441: You can also save the plot to disk using ``--save-image``. The following example
amine@432: demonstrates both:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok -p --save-image "plot.png" # can also be 'pdf' or another image format
amine@379: 
amine@379: output example:
amine@379: 
amine@379: .. image:: figures/example_1.png
amine@379: 
amine@379: Plotting requires `matplotlib <https://matplotlib.org/stable/index.html>`_.