aubio  0.4.1
onset/onset.h
Go to the documentation of this file.
00001 /*
00002   Copyright (C) 2006-2013 Paul Brossier <piem@aubio.org>
00003 
00004   This file is part of aubio.
00005 
00006   aubio is free software: you can redistribute it and/or modify
00007   it under the terms of the GNU General Public License as published by
00008   the Free Software Foundation, either version 3 of the License, or
00009   (at your option) any later version.
00010 
00011   aubio is distributed in the hope that it will be useful,
00012   but WITHOUT ANY WARRANTY; without even the implied warranty of
00013   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014   GNU General Public License for more details.
00015 
00016   You should have received a copy of the GNU General Public License
00017   along with aubio.  If not, see <http://www.gnu.org/licenses/>.
00018 
00019 */
00020 
00021 /** \file
00022 
00023   Onset detection object
00024 
00025   The following routines compute the onset detection function and detect peaks
00026   in these functions. When onsets are found above a given silence threshold,
00027   and after a minimum inter-onset interval, the output vector returned by
00028   aubio_onset_do() is filled with `1`. Otherwise, the output vector remains
00029   `0`.
00030 
00031   The peak-picking threshold, the silence threshold, and the minimum
00032   inter-onset interval can be adjusted during the execution of the
00033   aubio_onset_do routine using the corresponding functions.
00034 
00035   \example onset/test-onset.c
00036   \example examples/aubioonset.c
00037   \example examples/aubionotes.c
00038 
00039 */
00040 
00041 
00042 #ifndef _AUBIO_ONSET_H
00043 #define _AUBIO_ONSET_H
00044 
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #endif
00048 
00049 /** onset detection object */
00050 typedef struct _aubio_onset_t aubio_onset_t;
00051 
00052 /** create onset detection object
00053 
00054   \param method onset detection type as specified in specdesc.h
00055   \param buf_size buffer size for phase vocoder
00056   \param hop_size hop size for phase vocoder
00057   \param samplerate sampling rate of the input signal
00058 
00059   \return newly created ::aubio_onset_t
00060 
00061 */
00062 aubio_onset_t * new_aubio_onset (char_t * method,
00063     uint_t buf_size, uint_t hop_size, uint_t samplerate);
00064 
00065 /** execute onset detection
00066 
00067   \param o onset detection object as returned by new_aubio_onset()
00068   \param input new audio vector of length hop_size
00069   \param onset output vector of length 1, containing 0 if no onset was found,
00070   and a value equal or greater than 1 otherwise
00071 
00072   When no onset was detected, the first element of the output vector `onset`
00073   is set to 0.
00074 
00075   When an onset is found, the first element of the output vector `onset` is set
00076   to `offset = 1 + a` where `a` is a number in the range`[0, 1]`.
00077 
00078   The final onset detection time, in samples, can be obtained with
00079   aubio_onset_get_last(). It can also be derived from `offset` as
00080   follows:
00081 
00082   \code
00083     t = total_frames + offset * hop_size - delay
00084   \endcode
00085 
00086   where `total_frames` is the total number of frames processed so far, and
00087   `delay` is the current delay of the onset object, as returned by
00088   aubio_onset_get_delay().
00089 
00090 */
00091 void aubio_onset_do (aubio_onset_t *o, fvec_t * input, fvec_t * onset);
00092 
00093 /** get the time of the latest onset detected, in samples
00094 
00095   \param o onset detection object as returned by new_aubio_onset()
00096 
00097   \return onset detection timestamps (in samples)
00098 
00099 */
00100 uint_t aubio_onset_get_last (aubio_onset_t *o);
00101 
00102 /** get the time of the latest onset detected, in seconds
00103 
00104   \param o onset detection object as returned by new_aubio_onset()
00105 
00106   \return onset detection timestamps (in seconds)
00107 
00108 */
00109 smpl_t aubio_onset_get_last_s (aubio_onset_t *o);
00110 
00111 /** get the time of the latest onset detected, in milliseconds
00112 
00113   \param o onset detection object as returned by new_aubio_onset()
00114 
00115   \return onset detection timestamps (in milliseconds)
00116 
00117 */
00118 smpl_t aubio_onset_get_last_ms (aubio_onset_t *o);
00119 
00120 /** set onset detection silence threshold
00121 
00122   \param o onset detection object as returned by new_aubio_onset()
00123   \param silence new silence detection threshold
00124 
00125 */
00126 uint_t aubio_onset_set_silence(aubio_onset_t * o, smpl_t silence);
00127 
00128 /** get onset detection function
00129 
00130   \param o onset detection object as returned by new_aubio_onset()
00131   \return the current value of the descriptor
00132 
00133 */
00134 smpl_t aubio_onset_get_descriptor ( aubio_onset_t *o);
00135 
00136 /** get thresholded onset detection function
00137 
00138   \param o onset detection object as returned by new_aubio_onset()
00139   \return the value of the thresholded descriptor
00140 
00141 */
00142 smpl_t aubio_onset_get_thresholded_descriptor ( aubio_onset_t *o);
00143 
00144 /** set onset detection peak picking threshold
00145 
00146   \param o onset detection object as returned by new_aubio_onset()
00147   \param threshold new peak-picking threshold
00148 
00149 */
00150 uint_t aubio_onset_set_threshold(aubio_onset_t * o, smpl_t threshold);
00151 
00152 /** set minimum inter onset interval in samples
00153 
00154   \param o onset detection object as returned by new_aubio_onset()
00155   \param minioi minimum interval between two consecutive onsets (in
00156   samples)
00157 
00158 */
00159 uint_t aubio_onset_set_minioi(aubio_onset_t * o, uint_t minioi);
00160 
00161 /** set minimum inter onset interval in seconds
00162 
00163   \param o onset detection object as returned by new_aubio_onset()
00164   \param minioi minimum interval between two consecutive onsets (in
00165   seconds)
00166 
00167 */
00168 uint_t aubio_onset_set_minioi_s(aubio_onset_t * o, smpl_t minioi);
00169 
00170 /** set minimum inter onset interval in milliseconds
00171 
00172   \param o onset detection object as returned by new_aubio_onset()
00173   \param minioi minimum interval between two consecutive onsets (in
00174   milliseconds)
00175 
00176 */
00177 uint_t aubio_onset_set_minioi_ms(aubio_onset_t * o, smpl_t minioi);
00178 
00179 /** set minimum inter onset interval in samples
00180 
00181   \param o onset detection object as returned by new_aubio_onset()
00182   \param delay constant system delay to take back from detection time
00183   (in samples)
00184 
00185 */
00186 uint_t aubio_onset_set_delay(aubio_onset_t * o, uint_t delay);
00187 
00188 /** set minimum inter onset interval in seconds
00189 
00190   \param o onset detection object as returned by new_aubio_onset()
00191   \param delay constant system delay to take back from detection time
00192   (in seconds)
00193 
00194 */
00195 uint_t aubio_onset_set_delay_s(aubio_onset_t * o, smpl_t delay);
00196 
00197 /** set minimum inter onset interval in milliseconds
00198 
00199   \param o onset detection object as returned by new_aubio_onset()
00200   \param delay constant system delay to take back from detection time
00201   (in milliseconds)
00202 
00203 */
00204 uint_t aubio_onset_set_delay_ms(aubio_onset_t * o, smpl_t delay);
00205 
00206 /** get minimum inter onset interval in samples
00207 
00208   \param o onset detection object as returned by new_aubio_onset()
00209   \return minimum interval between two consecutive onsets (in
00210   samples)
00211 
00212 */
00213 uint_t aubio_onset_get_minioi(aubio_onset_t * o);
00214 
00215 /** get minimum inter onset interval in seconds
00216 
00217   \param o onset detection object as returned by new_aubio_onset()
00218   \return minimum interval between two consecutive onsets (in
00219   seconds)
00220 
00221 */
00222 smpl_t aubio_onset_get_minioi_s(aubio_onset_t * o);
00223 
00224 /** get minimum inter onset interval in milliseconds
00225 
00226   \param o onset detection object as returned by new_aubio_onset()
00227   \return minimum interval between two consecutive onsets (in
00228   milliseconds)
00229 
00230 */
00231 smpl_t aubio_onset_get_minioi_ms(aubio_onset_t * o);
00232 
00233 /** get minimum inter onset interval in samples
00234 
00235   \param o onset detection object as returned by new_aubio_onset()
00236   \return constant system delay to take back from detection time
00237   (in samples)
00238 
00239 */
00240 uint_t aubio_onset_get_delay(aubio_onset_t * o);
00241 
00242 /** get minimum inter onset interval in seconds
00243 
00244   \param o onset detection object as returned by new_aubio_onset()
00245   \return constant system delay to take back from detection time
00246   (in seconds)
00247 
00248 */
00249 smpl_t aubio_onset_get_delay_s(aubio_onset_t * o);
00250 
00251 /** get minimum inter onset interval in milliseconds
00252 
00253   \param o onset detection object as returned by new_aubio_onset()
00254   \return constant system delay to take back from detection time
00255   (in milliseconds)
00256 
00257 */
00258 smpl_t aubio_onset_get_delay_ms(aubio_onset_t * o);
00259 
00260 /** get onset peak picking threshold
00261 
00262   \param o onset detection object as returned by new_aubio_onset()
00263   \return current onset detection threshold
00264 
00265 */
00266 smpl_t aubio_onset_get_threshold(aubio_onset_t * o);
00267 
00268 /** delete onset detection object
00269 
00270   \param o onset detection object to delete
00271 
00272 */
00273 void del_aubio_onset(aubio_onset_t * o);
00274 
00275 #ifdef __cplusplus
00276 }
00277 #endif
00278 
00279 #endif /* _AUBIO_ONSET_H */
 All Data Structures Files Functions Variables Typedefs Defines