# -*- coding: utf-8 -*-

# Copyright (c) 2010-2013 Christopher Brown
#
# This file is part of Snail.
#
# Snail is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Snail is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Snail.  If not, see <http://www.gnu.org/licenses/>.
#
# Comments and/or additions are welcome. Send e-mail to: cbrown1@pitt.edu.
#

#import numpy as np
import _st
import _yin

__version__='1.0',
__doc__="""
Pitch-related function.

Provides:
	yin.get_pitch, Estimates the pitch of a signal.
	st.shift_pitch, Performs frequency compression/expansion on a signal.

Notes:
The shift_pitch function depends on soundtouch being installed on your system.
"""
__author__='Christopher A. Brown',
__author_email__ = "cbrown1@pitt.edu",
__maintainer__ = "Christopher Brown",
__maintainer_email__ = "cbrown1@pitt.edu",
__url__ = "http://pysnail.googlecode.com/",
#__st_libversion__ = _snail.get_st_LibVersion()

def get_pitch (sig, fs, threshold=.15, buffer_size=2048, overlap=0):
    """
    Estimates the pitch of a signal.

    Parameters
    ----------
    sig : array
        The input signal. Must be 1d.
    fs : int
        The sampling frequency.
    threshold : float
        Allowed uncertainty. Values can be 0 <= 1.
		(e.g 0.05 will return a pitch with ~95% probability).
    buffer_size : int
        The analysis buffer size, in samples. Default = 2048.

    Returns
    -------
    pitch : array
        The pitch track. Will be of size (sig.size/buffer_size).
    probability : array
        For each pitch estimate, the certainty of the accuracy. 
		Values will be 0 <= 1. Will be same size as pitch.

    Notes
    -----
	Uses the Yin algorithm, a well-established autocorrelation 
	based pitch algorith. Read a paper on Yin here:
	http://audition.ens.fr/adc/pdf/2002_JASA_YIN.pdf

	The C implementation of Yin was downloaded on 2013-09-21 from:
	https://github.com/ashokfernandez/Yin-Pitch-Tracking
	and has been modified significantly. It now works on doubles,
	and has no (known) memory leaks. There are a few other tweaks 
	as well.
    """
    pitch,prob = _yin.get_pitch(sig, fs, threshold, buffer_size, overlap)
    return pitch,prob

def shift_pitch(sig, fs, alpha, quick=True, aa=True, buffer_size=2048):
    """
    Applies a specified amount of freq compression/expansion to a signal.

    Parameters
    ----------
    sig : array
        The input signal. Must be 1d.
    fs : int
        The sampling frequency.
    alpha : float
        The pitch change, in octaves. -1 = 1 octave of compression, 0 = no 
        change, 1 = 1 octave of expansion.
    quick : bool
        True = use soundtouch's 'quick' setting, which speeds up processing
        significantly, with a small degredation in quality. Default = True.
    aa : bool
        Whether to use soundtouch's anti-aliasing filter. Default = True.
    buffer_size : int
        The analysis buffer size, in samples. Default = 2048.

    Returns
    -------
    sig : array
        The signal with specified amount of freq compression/expansion applied.

    Notes
    -----
    Due to soundtouch's reliance on interpolation, the output buffer may 
    differ in length slightly from the input buffer.

    Works with mono or stereo data (1 or 2 rows).

    Uses the soundtouch library: http://www.surina.net/soundtouch/
    """
    ret = _st.shift_pitch(sig, fs, alpha, quick, aa, buffer_size)
    return ret

