annotate README @ 164:a7d9c6142f8f tip

Added tag v1.2 for changeset 4a97f7638ffd
author Chris Cannam
date Thu, 06 Feb 2020 15:02:47 +0000
parents c808472d80e7
children
rev   line source
Chris@9 1
Chris@9 2 pYIN
Chris@9 3 ====
Chris@9 4
Chris@9 5 pYIN is a modification of the well-loved YIN algorithm for fundamental
Chris@9 6 frequency (F0) estimation in monophonic audio.
Chris@9 7
Chris@159 8 This is a Vamp plugin (https://vamp-plugins.org) implementation of
Chris@9 9 pYIN, as well as the original YIN method. The plugin can be used by
Chris@9 10 any Vamp host such as Sonic Visualiser and Sonic Annotator.
Chris@9 11
Chris@9 12
Chris@9 13 Method
Chris@9 14 ======
Chris@9 15
Chris@9 16 The pYIN method is a modification of the method known as YIN (De
Chris@9 17 Cheveigné, Alain, and Hideki Kawahara. "YIN, a fundamental frequency
Chris@9 18 estimator for speech and music." The Journal of the Acoustical Society
Chris@9 19 of America 111 (2002)).
Chris@9 20
Chris@9 21 The original YIN has one threshold parameter. In pYIN this parameter
Chris@9 22 is replaced by a parameter distribution, and for every frame several
Chris@9 23 fundamental frequency candidates obtained, conditional on this prior
Chris@9 24 parameter distribution. In the second phase, a hidden Markov model
Chris@9 25 (HMM) is Viterbi-decoded to find a "smooth" path through the
Chris@9 26 fundamental frequency candidates. Note that this smoothed path is not
Chris@9 27 smudging or averaging pitch estimates: any pitch estimate contains
Chris@9 28 only fundamental frequency estimates that are genuine estimates of the
Chris@9 29 original YIN method for some threshold parameter.
Chris@9 30
Chris@9 31 The note estimator is a post-processing step on the pYIN pitch track,
Chris@9 32 also performed as Viterbi decoding of an HMM.
Chris@9 33
Chris@9 34
Chris@9 35 Limitations
Chris@9 36 ===========
Chris@9 37
Chris@9 38 The pYIN method is designed to reliably extract the fundamental
Chris@9 39 frequency of audio recordings of a monophonic, harmonic instrument
Chris@9 40 such as the human voice. Being based on YIN means that pYIN exploits
Chris@9 41 the periodicity of the signal. In some circumstances it will not be
Chris@9 42 reliable. Such circumstances occur, e.g.
Chris@9 43
Chris@9 44 ... if the source audio is not monophonic, e.g. a singer with
Chris@9 45 accompanying instruments,
Chris@9 46
Chris@9 47 ... if the recording has reverb/echo (this essentially makes it
Chris@9 48 polyphonic),
Chris@9 49
Chris@9 50 ... if, in a stringed instrument such as the cello, one string
Chris@9 51 keeps ringing while the melody turns to a different pitch.
Chris@9 52
Chris@9 53
Chris@9 54 Authors, Citation, License and Use
Chris@9 55 ==================================
Chris@9 56
Chris@159 57 pYIN was written by Matthias Mauch. Copyright 2012-2020 Matthias Mauch
Chris@9 58 and Queen Mary, University of London.
Chris@9 59
Chris@9 60 The YIN code was drawn from the Java implementation in the TarsosDSP
Chris@9 61 library by Joren Six.
Chris@9 62
Chris@9 63 If you make use of this software for any public or commercial purpose,
Chris@9 64 we ask you to kindly mention the authors and Queen Mary, University of
Chris@9 65 London in your user-visible documentation. We're very happy to see
Chris@9 66 this sort of use but would much appreciate being credited, separately
Chris@9 67 from the requirements of the software license itself (see below).
Chris@9 68
Chris@9 69 If you make use of this software for academic purposes, please cite
Chris@9 70 one of the publications indicated on the Publications page:
Chris@9 71
Chris@9 72 https://code.soundsoftware.ac.uk/publications?project_id=pyin
Chris@9 73
Chris@9 74 This program is free software: you can redistribute it and/or modify
Chris@9 75 it under the terms of the GNU General Public License as published by
Chris@9 76 the Free Software Foundation, either version 2 of the License, or (at
Chris@9 77 your option) any later version.
Chris@9 78
Chris@9 79 This program is distributed in the hope that it will be useful, but
Chris@9 80 WITHOUT ANY WARRANTY; without even the implied warranty of
Chris@9 81 MERCHANTABILITY or FITNESS FOR A ARTICULAR PURPOSE. See the GNU
Chris@9 82 General Public License for more details. You should have received a
Chris@9 83 copy of the GNU General Public License along with this program. If
Chris@9 84 not, see http://www.gnu.org/licenses/.
Chris@9 85