comparison doc/command_line_usage.rst @ 450:ea94b19d13cb

Merge branch 'master' of https://github.com/amsehili/auditok

 about available parameters and descriptions, type:
 
 .. code:: bash
 
     auditok -h
+
+
+.. code::
+
+    usage: auditok [-h] [--version] [-I INT] [-F INT] [-f STRING] [-M FLOAT] [-L] [-O FILE] [-o STRING] [-j FLOAT] [-T STRING] [-u INT/STRING]
+               [-a FLOAT] [-n FLOAT] [-m FLOAT] [-s FLOAT] [-d] [-R] [-e FLOAT] [-r INT] [-c INT] [-w INT] [-C STRING] [-E] [-B] [-p]
+               [--save-image FILE] [--printf STRING] [--time-format STRING] [--timestamp-format TIMESTAMP_FORMAT] [-q] [-D] [--debug-file FILE]
+               [input]
+
+    auditok, an audio tokenization tool.
+
+    options:
+    -h, --help            show this help message and exit
+    --version, -v         show program's version number and exit
+    -q, --quiet           Quiet mode: Do not display any information on the screen.
+    -D, --debug           Debug mode: output processing operations to STDOUT.
+    --debug-file FILE     Save processing operations to the specified file.
+
+    Input-Output options::
+    input                 Input audio or video file. Use '-' for stdin [Default: read from a microphone using PyAudio].
+    -I INT, --input-device-index INT
+                            Audio device index [Default: None]. Optional and only effective when using PyAudio.
+    -F INT, --audio-frame-per-buffer INT
+                            Audio frame per buffer [Default: 1024]. Optional and only effective when using PyAudio.
+    -f STRING, --input-format STRING
+                            Specify the input audio file format. If not provided, the format is inferred from the file extension. If the output file
+                            name lacks an extension, the format is guessed from the file header (requires pydub). If neither condition is met, an
+                            error is raised.
+    -M FLOAT, --max-read FLOAT
+                            Maximum data (in seconds) to read from a microphone or a file [Default: read until the end of the file or stream].
+    -L, --large-file      Whether the input file should be treated as a large file. If True, data will be read from file on demand, otherwise all
+                            audio data is loaded into memory before tokenization.
+    -O FILE, --save-stream FILE
+                            Save read audio data (from a file or a microphone) to a file. If omitted, no audio data will be saved.
+    -o STRING, --save-detections-as STRING
+                            Specify the file name format to save detected events. You can use the following placeholders to construct the output
+                            file name: {id} (sequential, starting from 1), {start}, {end}, and {duration}. Time placeholders are in seconds.
+                            Example: 'Event_{id}{start}-{end}{duration:.3f}.wav'
+    -j FLOAT, --join-detections FLOAT
+                            Join (glue) detected audio events with a specified duration of silence between them. To be used in combination with the
+                            --save-stream / -O option.
+    -T STRING, --output-format STRING
+                            Specify the audio format for saving detections and/or the main stream. If not provided, the format will be (1) inferred
+                            from the file extension or (2) default to raw format.
+    -u INT/STRING, --use-channel INT/STRING
+                            Specify the audio channel to use for tokenization when the input stream is multi-channel (0 refers to the first
+                            channel). By default, this is set to None, meaning all channels are used, capturing any valid audio event from any
+                            channel. Alternatively, set this to 'mix' (or 'avg'/'average') to combine all channels into a single averaged channel
+                            for tokenization. Regardless of theoption chosen, saved audio events will have the same number of channels as the input
+                            stream. [Default: None, use all channels].
+
+    Tokenization options::
+    Set audio events' duration and set the threshold for detection.
+
+    -a FLOAT, --analysis-window FLOAT
+                            Specify the size of the analysis window in seconds. [Default: 0.01 (10ms)].
+    -n FLOAT, --min-duration FLOAT
+                            Minimum duration of a valid audio event in seconds. [Default: 0.2].
+    -m FLOAT, --max-duration FLOAT
+                            Maximum duration of a valid audio event in seconds. [Default: 5].
+    -s FLOAT, --max-silence FLOAT
+                            Maximum duration of consecutive silence allowed within a valid audio event in seconds. [Default: 0.3]
+    -d, --drop-trailing-silence
+                            Remove trailing silence from a detection. [Default: trailing silence is retained].
+    -R, --strict-min-duration
+                            Reject events shorter than --min-duration, even if adjacent to the most recent valid event that reached max-duration.
+                            [Default: retain such events].
+    -e FLOAT, --energy-threshold FLOAT
+                            Set the log energy threshold for detection. [Default: 50]
+
+    Audio parameters::
+    Set audio parameters when reading from a headerless file (raw or stdin) or when using custom microphone settings.
+
+    -r INT, --rate INT    Sampling rate of audio data [Default: 16000].
+    -c INT, --channels INT
+                            Number of channels of audio data [Default: 1].
+    -w INT, --width INT   Number of bytes per audio sample [Default: 2].
+
+    Use audio events::
+    Use these options to print, play, or plot detected audio events.
+
+    -C STRING, --command STRING
+                            Provide a command to execute when an audio event is detected. Use '{file}' as a placeholder for the temporary WAV file
+                            containing the event data (e.g., `-C 'du -h {file}'` to display the file size or `-C 'play -q {file}'` to play audio
+                            with sox).
+    -E, --echo            Immediately play back a detected audio event using pyaudio.
+    -B, --progress-bar    Show a progress bar when playing audio.
+    -p, --plot            Plot and displays the audio signal along with detections (requires matplotlib).
+    --save-image FILE     Save the plotted audio signal and detections as a picture or a PDF file (requires matplotlib).
+    --printf STRING       Prints information about each audio event on a new line using the specified format. The format can include text and
+                            placeholders: {id} (sequential, starting from 1), {start}, {end}, {duration}, and {timestamp}. The first three time
+                            placeholders are in seconds, with formatting controlled by the --time-format argument. {timestamp} represents the system
+                            date and time of the event, configurable with the --timestamp-format argument. Example: '[{id}]: {start} -> {end} --
+                            {timestamp}'.
+    --time-format STRING  Specify the format for printing {start}, {end}, and {duration} placeholders with --printf. [Default: %S]. Accepted
+                            formats are : - %S: absolute time in seconds - %I: absolute time in milliseconds - %h, %m, %s, %i: converts time into
+                            hours, minutes, seconds, and milliseconds (e.g., %h:%m:%s.%i) and only displays provided fields. Note that %S and %I can
+                            only be used independently.
+    --timestamp-format TIMESTAMP_FORMAT
+                            Specify the format used for printing {timestamp}. Should be a format accepted by the 'datetime' standard module.
+                            [Default: '%Y/%m/%d %H:%M:%S'].
+
 
 Below, we provide several examples covering the most common use cases.
 
 
 Real-Time audio acquisition and event detection