//#################################### soundfiles.lib ########################################
// A library to handle soundfiles in Faust. Its official prefix is `so`.
//
// #### References
// * <https://github.com/grame-cncm/faustlibraries/blob/master/soundfiles.lib>
//########################################################################################

/************************************************************************
************************************************************************
FAUST library file
Copyright (C) 2018-2020 GRAME, Centre National de Creation Musicale
----------------------------------------------------------------------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.

This program 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with the GNU C Library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA.

EXCEPTION TO THE LGPL LICENSE : As a special exception, you may create a
larger FAUST program which directly or indirectly imports this library
file and still distribute the compiled code generated by the FAUST
compiler, or a modified version of this compiled code, under your own
copyright and license. This EXCEPTION TO THE LGPL LICENSE explicitly
grants you the right to freely choose the license for the resulting
compiled code. In particular the resulting compiled code has no obligation
to be LGPL or GPL. For example you are free to choose a commercial or
closed source license or any other license if you decide so.
************************************************************************
************************************************************************/

ba = library("basics.lib");
ma = library("maths.lib");
si = library("signals.lib");
ro = library("routes.lib");
it = library("interpolators.lib");

declare name "Faust Soundfile Library";
declare version "1.7.0";

//=======================================================================
// Utility functions added in a 'super' environment (to test the idea...)
//=======================================================================

super = environment {

    length(sf, part) = (part, 0) : sf : (_,si.block(outputs(sf)-1));  
    srate(sf, part) = (part, 0) : sf : (!,_,si.block(outputs(sf)-2)) : float;
    outs(sf, level) = sf : si.block(2), bus(outputs(sf)-2) with { bus(n) = par(i,n,*(level)); };

    // Plays a soundfile
    // 'reader' in a function of type \(sf,part).(body) whih produces the (possibly fractional) read index
    player(sf, part, reader, level) = (part, it.int_part(reader(sf, part))) : outs(sf, level);

    // Plays a soundfile with configurable interpolation
    player_interp(sf, part, reader, level, selector) = it.interpolator_select(gen, idv, selector)
    with {
        // Adapts the (sf, part, reader) parameters as 'idv' and 'gen' types for the generic interpolator
        idv = reader(sf, part);
        gen(idx) = (part, idx) : outs(sf, level);
    };

     // Plays a soundfile with configurable interpolation and a reference frequence 'ref'
    play_interp(sf, part, ref, freq, level, gate, selector) = player_interp(sf, part, reader, level, selector)
    with {
        reader(sf, part) = it.raise(gate, step, length(sf, part)) with { step = freq/ref*srate(sf, part)/ma.SR; };
    };

    // Generic version
    loop_speed_level(sf, part, speed, level) = player(sf, part, reader, level)
    with {
        // A 'reader' which loops the sound with 'speed' and 'level' control
        reader(sf, part) = it.raise_modulo(1, step, length(sf, part)) with { step = speed*srate(sf, part)/ma.SR; };
    };

    // Defines 'loop_speed' as a specialized version of loop_speed_level with level = 1
    loop_speed(sf, part, speed) = loop_speed_level(sf, part, speed, 1);

    // Defines 'loop_speed' as a specialized version of loop_speed_level with speed = 1 and level = 1
    loop(sf, part) = loop_speed_level(sf, part, 1, 1);


}; // End of environment

//=============================Functions Reference========================================
//========================================================================================

//--------------------------------`(so.)loop`-----------------------------------
// Play a soundfile in a loop taking into account its sampling rate.
// `loop` is a standard Faust function.
//
// #### Usage
//
// ```
// loop(sf, part) : si.bus(outputs(sf))
// ```
//
// Where:
//
// * `sf`: the soundfile
// * `part`: the part in the soundfile list of sounds
//
//-----------------------------------------------------------------------------

loop(sf, part) = super.loop(sf, part);

//--------------------------------`(so.)loop_speed`-----------------------------------
// Play a soundfile in a loop taking into account its sampling rate, with speed control.
// `loop_speed` is a standard Faust function.
//
// #### Usage
//
// ```
// loop_speed(sf, part, speed) : si.bus(outputs(sf))
// ```
//
// Where:
//
// * `sf`: the soundfile
// * `part`: the part in the soundfile list of sounds
// * `speed`: the speed between 0 and n
//
//-----------------------------------------------------------------------------

loop_speed(sf, part, speed) = super.loop_speed(sf, part, speed);

//--------------------------------`(so.)loop_speed_level`-----------------------------------
// Play a soundfile in a loop taking into account its sampling rate, with speed and level controls.
// `loop_speed_level` is a standard Faust function.
//
// #### Usage
//
// ```
// loop_speed_level(sf, part, speed, level) : si.bus(outputs(sf))
// ```
//
// Where:
//
// * `sf`: the soundfile
// * `part`: the part in the soundfile list of sounds
// * `speed`: the speed between 0 and n
// * `level`: the volume between 0 and n
//
//-----------------------------------------------------------------------------

loop_speed_level(sf, part, speed, level) = super.loop_speed_level(sf, part, speed, level);

//====================================================
// Environment to handle a given sound in a soundfile
//====================================================

sound(sf, part) = environment {

    // Looping the sound
    loop = super.loop(sf, part);
    loop_speed(speed) = super.loop_speed(sf, part, speed);
    loop_speed_level(speed, level) = super.loop_speed_level(sf, part, speed, level);

    // Play once
    play(level, gate) = super.player(sf, part, reader, level)
    with {
        reader(sf, part) = it.raise(gate, super.srate(sf, part)/ma.SR, super.length(sf, part));
    };

    // Play once in reverse
    play_rev(level, gate) = super.player(sf, part, reader, level)
    with {
        reader(sf, part) = it.decrease(gate, super.srate(sf, part)/ma.SR, super.length(sf, part));
    };

    // Play sound once with configurable interpolation and freq control (using a 'ref' value)
    play_interp(ref, freq, level, gate, selector) = super.play_interp(sf, part, ref, freq, level, gate, selector);

    // Play sound once and alternate between normal play and reverse play
    //play_alt(level, gate, ctrl) = super.player(sf, part, alt2(ramp1, ramp2, ctrl), level)
    play_alt(level, gate, ctrl) = super.player(sf, part, altN(lramp, ctrl), level)
    with {
        // High-order function which alternate between 2 'readers' depending of the 'ctrl' signal
       	alt2(r1, r2, ctrl) = \(sf, part).(ba.selectmulti(ma.SR/100, lr, ctrl) with { lr = r1(sf, part), r2(sf, part); });
        
        altN(lrs, ctrl) = \(sf, part).(ba.selectmulti(ma.SR/100, mapper(lrs), ctrl) 
        with { 
        	mapper((xs, xxs)) = xs(sf, part), mapper(xxs); 
        	mapper(xs) = xs(sf, part); 
        });
        
        step = super.srate(sf, part)/ma.SR;
        
        ramp1(sf, part) = it.raise(gate, step, super.length(sf, part));
        ramp2(sf, part) = it.decrease(gate, step, super.length(sf, part));
        
        lramp = (ramp1, ramp2, ramp2, ramp2, ramp1);
    };

}; // End of environment
							  
/*
// Using the `sound` environment allocated with a given `sf` and `part`

import("soundfiles.lib");

s1 = soundfile("[url:{'piano-C5.ogg';'piano-G5.ogg';'piano-C6.ogg';'piano-G6.ogg'}]",2);
sample1 = so.sound(s1, 0);
sample2 = so.sound(s1, 1);
sample3 = so.sound(s1, 2);

// Plays the sound in various ways
sample1.loop;
sample1.loop_speed(0.5);
sample1.loop_speed_level(0.5, 0.5);

sample2.play(0.5, button("gate"));
sample2.play_rev(0.5, button("gate"));
sample2.play_alt(0.5, button("gate"), checkbox("alt"));

sample3.play_interp(440.0, 600.0, 0.5, button("gate"), it.linear);
sample3.play_interp(440.0, 800.0, en.ar(0.1, 0.8, button("gate")), button("gate"), it.cubic);

play = button("gate");
sample3.play_interp(440.0,
                    hslider("freq", 200, 200, 880, 0.01), 
                    hslider("gain", 0.5, 0, 1, 0.01)*en.ar(0.1, 0.8, play), 
                    play,
                    nentry("interp", 0, 0, 3, 1));

*/