amine@379: ``auditok`` can also be used from the command-line. For more information about
amine@379: parameters and their description type:
amine@379: 
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok -h
amine@379: 
amine@379: In the following we'll a few examples that covers most use-cases.
amine@379: 
amine@379: 
amine@379: Read and split audio data online
amine@379: --------------------------------
amine@379: 
amine@379: To try ``auditok`` from the command line with you voice, you should either
amine@379: install `pyaudio <https://people.csail.mit.edu/hubert/pyaudio>`_ so that ``auditok``
amine@379: can directly read data from the microphone, or record data with an external program
amine@379: (e.g., `sox`) and redirect its output to ``auditok``.
amine@379: 
amine@379: Read data from the microphone (`pyaudio` installed):
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok
amine@379: 
amine@379: This will print the *id*, *start time* and *end time* of each detected audio
amine@379: event. Note that we didn't pass any additional arguments to the previous command,
amine@379: so ``auditok`` will use default values. The most important arguments are:
amine@379: 
amine@379: 
amine@379: - ``-n``, ``--min-duration`` : minimum duration of a valid audio event in seconds, default: 0.2
amine@379: - ``-m``, ``--max-duration`` : maximum duration of a valid audio event in seconds, default: 5
amine@379: - ``-s``, ``--max-silence`` : maximum duration of a consecutive silence within a valid audio event in seconds, default: 0.3
amine@379: - ``-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@379: 
amine@379: If you don't have `pyaudio`, you can use `sox` for data acquisition
amine@379: (`sudo apt-get install sox`) and make ``auditok`` read data 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@379: Note that when data is read from standard input, the same audio parameters must
amine@379: be used for both `sox` (or any other data generation/acquisition tool) and
amine@379: ``auditok``. The following table summarizes audio parameters.
amine@379: 
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@379: According to this table, the previous command can be run with the default
amine@379: parameters as:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     rec -q -t raw -r 16000 -c 1 -b 16 -e signed - | auditok -i -
amine@379: 
amine@379: Play back audio detections
amine@379: --------------------------
amine@379: 
amine@379: Use the ``-E`` option (for echo):
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: The second command works without further argument because data is recorded with
amine@379: ``auditok``'s default audio parameters . If one of the parameters is not at the
amine@379: default value you should specify it alongside ``-E``.
amine@379: 
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@379: Print out detection information
amine@379: -------------------------------
amine@379: 
amine@379: By default ``auditok`` prints out the **id**, the **start** and the **end** of
amine@379: each detected audio event. The latter two values represent the absolute position
amine@379: of the event within input stream (file or microphone) in seconds. The following
amine@379: listing is an example output with 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@379: the output would be something 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@379: Save detections
amine@379: ---------------
amine@379: 
amine@379: You can save audio events to disk as they're detected using ``-o`` or
amine@379: ``--save-detections-as``. To get a uniq file name for each event, you can use
amine@379: ``{id}``, ``{start}``, ``{end}`` and ``{duration}`` placeholders. Example:
amine@379: 
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok --save-detections-as "{id}_{start}_{end}.wav"
amine@379: 
amine@379: When using ``{start}``, ``{end}`` and ``{duration}`` placeholders, it's
amine@379: recommended that the number of decimals of the corresponding values be limited
amine@379: to 3. You can use something like:
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok -o "{id}_{start:.3f}_{end:.3f}.wav"
amine@379: 
amine@379: 
amine@379: Save whole audio stream
amine@379: -----------------------
amine@379: 
amine@379: When reading audio data from the microphone, you most certainly want to save it
amine@379: to disk. For this you can use the ``-O`` or ``--save-stream`` option.
amine@379: 
amine@379: .. code:: bash
amine@379: 
amine@379:     auditok --save-stream "stream.wav"
amine@379: 
amine@379: Note this will work even if you read data from another file on disk.
amine@379: 
amine@379: 
amine@379: Plot detections
amine@379: ---------------
amine@379: 
amine@379: Audio signal and detections can be plotted using the ``-p`` or ``--plot`` option.
amine@379: You can also save plot to disk using ``--save-image``. The following example
amine@379: does 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>`_.