-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Phase vocoder
--   
--   This package is an implementation of phase vocoder frequency domain
--   processing algorithms. It has minimal dependencies on external
--   libraries. It can be used directly, but for most uses it's more
--   convenient to use a streaming or FRP library wrapper. Packages
--   vocoder-conduit and vocoder-dunai are provided for this purpose.
@package vocoder
@version 0.1.0.0


-- | This module implements the phase vocoder algorithms. The
--   implementation is designed to be used directly or to be integrated
--   into some convenient abstraction (streaming or FRP).
module Vocoder

-- | Complex moduli of FFT frames. Represent signal amplitudes.
type Moduli = Vector Double

-- | Complex arguments of FFT frames. Represent signal phases.
type Phase = Vector Double

-- | Phase increments. Represent the deviation of the phase difference
--   between successive frames from the expected difference for the center
--   frequencies of the FFT bins.
type PhaseInc = Vector Double

-- | Time domain frame.
type Frame = Vector Double

-- | Sampled STFT window function.
type Window = Frame

-- | Offset between successive STFT frames, in samples.
type HopSize = Int

-- | Size in samples.
type Length = Int

-- | STFT processing unit.
type STFTFrame = (Moduli, PhaseInc)

-- | Frequency domain frame.
type FFTOutput = Vector (Complex Double)

-- | Configuration parameters for the phase vocoder algorithm.
data VocoderParams

-- | Create a vocoder configuration.
vocoderParams :: Length -> HopSize -> Window -> VocoderParams

-- | FFT frame length. Can be larger than <a>vocInputFrameLength</a> for
--   zero-padding.
vocFrameLength :: VocoderParams -> Length

-- | STFT frame length.
vocInputFrameLength :: VocoderParams -> Length

-- | FFT frequency frame length.
vocFreqFrameLength :: VocoderParams -> Length

-- | STFT hop size.
vocHopSize :: VocoderParams -> HopSize

-- | Window function used during analysis and synthesis.
vocWindow :: VocoderParams -> Window

-- | Perform FFT processing, which includes the actual FFT, rewinding,
--   zero-paddding and windowing.
doFFT :: VocoderParams -> Frame -> FFTOutput

-- | Perform IFFT processing, which includes the actual IFFT, rewinding,
--   removing padding and windowing.
doIFFT :: VocoderParams -> FFTOutput -> Frame

-- | Perform FFT transform and frequency-domain analysis.
analysisBlock :: VocoderParams -> Phase -> Frame -> (Phase, STFTFrame)

-- | Analyze a frequency domain frame. Phase from a previous frame must be
--   supplied. It returns the phase of the analyzed frame and the result.
analysisStep :: HopSize -> Length -> Phase -> FFTOutput -> (Phase, STFTFrame)

-- | Perform analysis on a sequence of frames. This consists of FFT
--   processing and performing analysis on frequency domain frames.
analysisStage :: Traversable t => VocoderParams -> Phase -> t Frame -> (Phase, t STFTFrame)

-- | Perform frequency-domain synthesis and IFFT transform.
synthesisBlock :: VocoderParams -> Phase -> STFTFrame -> (Phase, Frame)

-- | Synthesize a frequency domain frame. Phase from the previously
--   synthesized frame must be supplied. It returns the phase of the
--   synthesized frame and the result.
synthesisStep :: HopSize -> Phase -> STFTFrame -> (Phase, FFTOutput)

-- | Perform synthesis on a sequence of frames. This consists of performing
--   synthesis and IFFT processing.
synthesisStage :: Traversable t => VocoderParams -> Phase -> t STFTFrame -> (Phase, t Frame)

-- | Zero phase for a given vocoder configuration. Can be used to
--   initialize the synthesis stage.
zeroPhase :: VocoderParams -> Phase

-- | An amplitude change coefficient for the processing pipeline. Can be
--   used to ensure that the output has the same volume as the input.
volumeCoeff :: VocoderParams -> Double

-- | Converts frame representation to magnitude and phase.
frameFromComplex :: FFTOutput -> STFTFrame

-- | Converts frame representation to complex numbers.
frameToComplex :: STFTFrame -> FFTOutput

-- | Adds STFT frames.
addFrames :: STFTFrame -> STFTFrame -> STFTFrame


-- | This module defines popular window functions for use in the vocoder
--   framework.
module Vocoder.Window

-- | Creates a window of given length by sampling a function on the
--   interval [0,1].
makeWindow :: (Double -> Double) -> Length -> Window

-- | Creates a box window.
boxWindow :: Length -> Window

-- | Creates a triangular window.
triangleWindow :: Length -> Window

-- | Creates a Hamming window.
hammingWindow :: Length -> Window

-- | Creates a Hann window.
hannWindow :: Length -> Window

-- | Creates a generalized Blackman window for a given alpha value.
generalizedBlackmanWindow :: Double -> Length -> Window

-- | Creates a Blackman window (with alpha=0.16).
blackmanWindow :: Length -> Window

-- | Creates an exact Blackman window.
exactBlackmanWindow :: Length -> Window

-- | Creates a Lanczos window.
lanczosWindow :: Length -> Window

-- | Creates a flat top window.
flatTopWindow :: Length -> Window


-- | This module defines some useful frequency-domain filters for use in
--   the vocoder framework.
module Vocoder.Filter

-- | A frequency step is a coefficient relating physical frequency (in Hz)
--   to FFT bin numbers. It is used to define filters independently of the
--   FFT window size.
type FreqStep = Double

-- | The type of frequency-domain filters. A frequency-domain filter is a
--   function transforming STFT frames which can depend on the frequency
--   step.
type Filter m = FreqStep -> STFTFrame -> m STFTFrame

-- | Sequential composition of filters.
composeFilters :: Monad m => Filter m -> Filter m -> Filter m

-- | Addition of filters.
addFilters :: Monad m => Filter m -> Filter m -> Filter m

-- | Identity filter.
idFilter :: Monad m => Filter m

-- | Creates a filter which transforms only amplitudes, leaving phase
--   increments unchanged.
amplitudeFilter :: Monad m => (FreqStep -> Moduli -> Moduli) -> Filter m

-- | Creates a filter which scales amplitudes depending on frequency.
linearAmplitudeFilter :: Monad m => (Double -> Double) -> Filter m

-- | Creates an "amplifier" which scales all frequencies.
amplify :: Monad m => Double -> Filter m

-- | Creates a brickwall lowpass filter.
lowpassBrickwall :: Monad m => Double -> Filter m

-- | Creates a brickwall highpass filter.
highpassBrickwall :: Monad m => Double -> Filter m

-- | Creates a brickwall bandpass filter.
bandpassBrickwall :: Monad m => Double -> Double -> Filter m

-- | Creates a brickwall bandstop filter.
bandstopBrickwall :: Monad m => Double -> Double -> Filter m

-- | Creates an n-th degree Butterworth-style lowpass filter.
lowpassButterworth :: Monad m => Double -> Double -> Filter m

-- | Creates an n-th degree Butterworth-style highpass filter.
highpassButterworth :: Monad m => Double -> Double -> Filter m

-- | Creates an n-th degree Butterworth-style bandpass filter.
bandpassButterworth :: Monad m => Double -> Double -> Double -> Filter m

-- | Creates an n-th degree Butterworth-style bandstop filter.
bandstopButterworth :: Monad m => Double -> Double -> Double -> Filter m

-- | Creates an interpolative pitch-shifting filter.
pitchShiftInterpolate :: Monad m => Double -> Filter m

-- | Convolves the amplitude spectrum using a kernel.
convolution :: Vector Double -> Moduli -> Moduli

-- | Creates a filter which convolves the spectrum using a kernel.
convolutionFilter :: Monad m => Vector Double -> Filter m

-- | Calculates the envelope of an amplitude spectrum using convolution.
envelope :: Length -> Moduli -> Moduli

-- | Creates a filter which replaces the amplitudes with their envelope.
envelopeFilter :: Monad m => Length -> Filter m

-- | Sets the phase increments so that the bins have horizontal
--   consistency. This erases the phase information, introducing
--   "phasiness".
randomPhaseFilter :: MonadIO m => Filter m