doc/: document -f --force-overwrite option
[aubio.git] / doc / aubioonset.txt
1 NAME
2   aubioonset - a command line tool to extract musical onset times
3
4 SYNOPSIS
5
6   aubioonset source
7   aubioonset [[-i] source] [-o sink]
8              [-r rate] [-B win] [-H hop]
9              [-O method] [-t thres]
10              [-s sil] [-m] [-f]
11              [-j] [-v] [-h]
12
13 DESCRIPTION
14
15   aubioonset attempts to detect onset times, the beginning of discrete sound
16   events, in audio signals.
17
18   When started with an input source (-i/--input), the detected onset times are
19   given on the console, in seconds.
20
21   When started without an input source, or with the jack option (-j/--jack),
22   aubioonset starts in jack mode.
23
24 OPTIONS
25
26   This program follows the usual GNU command line syntax, with long options
27   starting with two dashes (--). A summary of options is included below.
28
29   -i, --input source  Run analysis on this audio file. Most uncompressed and
30   compressed are supported, depending on how aubio was built.
31
32   -o, --output sink  Save results in this file. The file will be created on
33   the model of the input file. Onset times are marked by a short wood-block
34   like sound.
35
36   -r, --samplerate rate  Fetch the input source, resampled at the given
37   sampling rate. The rate should be specified in Hertz as an integer. If 0,
38   the sampling rate of the original source will be used. Defaults to 0.
39
40   -B, --bufsize win  The size of the buffer to analyze, that is the length
41   of the window used for spectral and temporal computations. Defaults to 512.
42
43   -H, --hopsize hop  The number of samples between two consecutive analysis.
44   Defaults to 256.
45
46   -O, --onset method  The onset detection method to use. See ONSET METHODS
47   below. Defaults to 'default'.
48
49   -t, --onset-threshold thres  Set the threshold value for the onset peak
50   picking. Typical values are typically within 0.001 and 0.900. Defaults to
51   0.1. Lower threshold values imply more onsets detected. Try 0.5 in case of
52   over-detections. Defaults to 0.3.
53
54   -s, --silence sil  Set the silence threshold, in dB, under which the pitch
55   will not be detected. A value of -20.0 would eliminate most onsets but the
56   loudest ones. A value of -90.0 would select all onsets. Defaults to -90.0.
57
58   -m, --mix-input  Mix source signal to the output signal before writing to
59   sink.
60
61   -f, --force-overwrite  Overwrite output file if it already exists.
62
63   -j, --jack  Use Jack input/output. You will need a Jack connection
64   controller to feed aubio some signal and listen to its output.
65
66   -h, --help  Print a short help message and exit.
67
68   -v, --verbose  Be verbose.
69
70 ONSET METHODS
71
72   Available methods are:
73
74   default  Default distance, currently hfc
75
76   Default: 'default' (currently set to hfc)
77
78   energy  Energy based distance
79
80   This function calculates the local energy of the input spectral frame.
81
82   hfc  High-Frequency content
83
84   This method computes the High Frequency Content (HFC) of the input
85   spectral frame. The resulting function is efficient at detecting
86   percussive onsets.
87
88   Paul Masri. Computer modeling of Sound for Transformation and Synthesis of
89   Musical Signal. PhD dissertation, University of Bristol, UK, 1996.
90
91   complex  Complex domain onset detection function
92
93   This function uses information both in frequency and in phase to determine
94   changes in the spectral content that might correspond to musical onsets.
95   It is best suited for complex signals such as polyphonic recordings.
96
97   Christopher Duxbury, Mike E. Davies, and Mark B. Sandler.  Complex domain
98   onset detection for musical signals. In Proceedings of the Digital Audio
99   Effects Conference, DAFx-03, pages 90-93, London, UK, 2003.
100
101   phase  Phase based onset detection function
102
103   This function uses information both in frequency and in phase to determine
104   changes in the spectral content that might correspond to musical onsets. It
105   is best suited for complex signals such as polyphonic recordings.
106
107   Juan-Pablo Bello, Mike P. Davies, and Mark B. Sandler.  Phase-based note
108   onset detection for music signals. In Proceedings of the IEEE International
109   Conference on Acoustics Speech and Signal Processing, pages 441­444,
110   Hong-Kong, 2003.
111
112   specdiff  Spectral difference onset detection function
113
114   Jonhatan Foote and Shingo Uchihashi. The beat spectrum: a new approach to
115   rhythm analysis. In IEEE International Conference on Multimedia and Expo
116   (ICME 2001), pages 881­884, Tokyo, Japan, August 2001.
117
118   kl  Kulback-Liebler onset detection function
119
120   Stephen Hainsworth and Malcom Macleod. Onset detection in music audio
121   signals. In Proceedings of the International Computer Music Conference
122   (ICMC), Singapore, 2003.
123
124   mkl  Modified Kulback-Liebler onset detection function
125
126   Paul Brossier, ``Automatic annotation of musical audio for interactive
127   systems'', Chapter 2, Temporal segmentation, PhD thesis, Centre for
128   Digital music, Queen Mary University of London, London, UK, 2006.
129
130   specflux  Spectral flux
131
132   Simon Dixon, Onset Detection Revisited, in ``Proceedings of the 9th
133   International Conference on Digital Audio Effects'' (DAFx-06), Montreal,
134   Canada, 2006.
135
136 SEE ALSO
137
138   aubiopitch(1),
139   aubiotrack(1),
140   aubionotes(1),
141   aubioquiet(1),
142   aubiomfcc(1),
143   and
144   aubiocut(1).
145
146 AUTHOR
147
148   This manual page was written by Paul Brossier <piem@aubio.org>. Permission is
149   granted to copy, distribute and/or modify this document under the terms of
150   the GNU General Public License as published by the Free Software Foundation,
151   either version 3 of the License, or (at your option) any later version.