May

module may.stream.framer;

/**

 * Framer expresses a stream (or a file) as a lazy list of (possibly

 * overlapping) frames of data.

 */

vec = load may.vector;

af = load may.stream.audiofile;

win = load may.signal.window;

fft = load may.transform.fft;

mat = load may.matrix;

complex = load may.complex;

cm = load may.matrix.complex;

manip = load may.stream.manipulate;

syn = load may.stream.syntheticstream;

{ ceil } = load may.mathmisc;

load may.stream.type;

//!!! todo: synchronized for everything with state assignment

blockList framesize stream =

    if stream.finished? then

        stream.close ();

        []

    else

        mat.resizedTo { rows = stream.channels, columns = framesize }

           (stream.read framesize)

            :. \(blockList framesize stream);

    fi;

overlappingBlockList size hop stream valid buffer =

   (m = stream.read hop;

    obtained = mat.width m;

    // Retain framesize - hop samples from old buffer, add hop samples

    // (zero-padded if necessary) just read

    buffer = map2

        do buf row:

            vec.concat

               [vec.slice buf hop size,

                vec.resizedTo hop (mat.getRow row m)];

        done buffer [0..stream.channels-1];

    // Number of "valid" elements (not tail-end zero-padding) left in buffer

    remaining = valid - (hop - obtained);

    if remaining <= 0 then

        stream.close ();

        [];

    else

        mat.fromRows buffer

            :. \(overlappingBlockList size hop stream remaining buffer);

    fi);

//!!! doc: if hop != framesize, stream will be padded at start with

// framesize - hop zeros if padded is true. if hop == framesize, no

// padding will occur at start regardless of the value of padded.  The

// end will always be padded (...?)

frames' framesize hop padded stream =

    if framesize == hop then

        blockList framesize stream

    else

        initialBuffer = 

            if padded then

                map \(vec.zeros framesize) [0..stream.channels-1];

            else 

                mat.asRows

                   (mat.concatHorizontal

                       [mat.toRowMajor

                           (mat.zeroMatrix { rows = stream.channels, columns = hop }),

                        stream.read (framesize - hop)]);

            fi;

        overlappingBlockList framesize hop stream framesize initialBuffer;

    fi;

frames framesize options stream =

   (var hop = framesize;

    var padded = true;

    var windower = id;

    var transform = id;

    var mixer = id;

    for options \case of

        Hop h: hop := h;

        Padded p: padded := p;

        Window w:

           (window = w framesize;

            windower := mat.mapRows (do v: vec.multiply [v, window] done));

        FrequencyDomain f:

            if f then

                transform := mat.mapRows (fft.realForwardMagnitude framesize);

            fi;

        MixedTo c:

            mixer := manip.mixedTo c;

    esac;

    map transform

       (map windower

           (frames' framesize hop padded

               (mixer stream))));

complexFrames framesize options stream =

   (var hop = framesize;

    var padded = true;

    var windower = id;

    var rowTransform = 

        do r: complex.complexArray r (vec.zeros (vec.length r)) done;

    var mixer = id;

    for options \case of

        Hop h: hop := h;

        Padded p: padded := p;

        Window w:

           (window = w framesize;

            windower := mat.mapRows (do v: vec.multiply [v, window] done));

        FrequencyDomain f:

        //!!! what if both f and not-f provided in one options list? need reset

            if f then 

                rowTransform := fft.realForward framesize;

            fi;

        MixedTo c:

            mixer := manip.mixedTo c;

    esac;

    map do m:

        cm.fromRows (map rowTransform (mat.asRows m))

        done

       (map windower

           (frames' framesize hop padded 

               (mixer stream))));

streamContiguous rate framesize frames =

   (var remaining = frames;

    var position = 0;

    channels = mat.height (head frames); // so we don't need to keep a head ptr

    var buffered = mat.toRowMajor

       (mat.zeroMatrix { rows = channels, columns = 0 });

    {

        get position () = position,

        get channels () = channels,

        get sampleRate () = rate,

        get finished? () = empty? remaining and mat.width buffered == 0,

        get available () = 

            // Don't take length of frames -- we don't want to lose laziness.

            // If the caller cares that much, they can measure frames themselves

            if empty? remaining then

                Known (mat.width buffered) 

            else

                Unknown ()

            fi,

        read count =

           (framesFor samples acc =

                if samples <= 0 or empty? remaining then

                    reverse acc

                else

                    this = head remaining;

                    remaining := tail remaining;

                    framesFor (samples - mat.width this) (this :: acc)

                fi;

            source = mat.concatHorizontal (framesFor count [buffered]);

            toReturn = mat.columnSlice source 0 count;

            position := position + mat.width toReturn;

            buffered := mat.columnSlice source count (mat.width source);

            toReturn),

        close = \(),

    });

overlapAdd overlap frames =

   (ola fr pending acc =

        case fr of

        first::rest:

           (w = mat.width pending;

            pre = mat.columnSlice pending 0 (w - overlap);

            added = mat.sum

               [first,

                (mat.resizedTo (mat.size first)

                    (mat.columnSlice pending (w - overlap) w))];

            ola rest added (pre::acc));

         _:

            reverse (pending::acc);

        esac;

    case frames of

    first::rest:

        mat.concatHorizontal (ola rest first []);

     _: 

        mat.toRowMajor (mat.zeroMatrix { rows = 0, columns = 0 });

    esac);

streamOverlapping rate { framesize, hop, window } frames =

   (var remaining = frames;

    var position = 0;

    factor = hop / (framesize/2);

    w = vec.scaled factor (window framesize);

    channels = mat.height (head frames); // so we don't need to keep a head ptr

    var buffered = 

        mat.toRowMajor (mat.zeroMatrix { rows = channels, columns = 0 });

    syncd = synchronized remaining;

    finished' () = syncd \(empty? remaining and mat.width buffered == 0);

    read' count = 

       (framesFor samples acc =

            if samples <= 0 or empty? remaining then

                reverse acc

            else

                this = mat.resizedTo { columns = framesize, rows = channels }

                   (mat.mapRows do v: vec.multiply [v,w] done (head remaining));

                remaining := tail remaining;

                framesFor (samples - hop) (this::acc)

            fi;

        source = overlapAdd (framesize - hop)

           (framesFor count [buffered]);

        buffered := mat.columnSlice source count (mat.width source);

        mat.columnSlice source 0 count);

    {

        get position () = syncd \(position),

        get channels () = channels,

        get sampleRate () = rate,

        get finished? () = finished' (),

        get available () = if finished' () then Known 0 else Unknown () fi,

        read count = syncd

          \(data = read' count;

            position := position + mat.width data;

            data),

        close = \(),

    });

//!!! doc: padded tells us whether the original framer was padding or

//not. if not, and if the frames are overlapping, we won't reconstruct

//the original stream exactly (scaling will be wrong for the first few

//samples until we reach the point where each sample is being

//reconstructed from the requisite number of frames)

streamed rate framesize options frames =

   (var hop = framesize;

    var padded = true;

    var winopt = None ();

    for options \case of

        Hop h: hop := h;

        Padded p: padded := p;

        Window w: winopt := Some w;

        FrequencyDomain f: failWith "Cannot stream from real input with FrequencyDomain true (need to use complexStreamed)";

    esac;

    window =

        case winopt of

        Some w: w;

        None (): 

            // NB periodic, not symmetric

            if framesize == hop then win.boxcar else win.hann fi

        esac;

    if empty? frames then

        syn.empty rate 1

    elif framesize == hop then

        streamContiguous rate framesize frames

    elif padded then

        manip.delayedBy (- (framesize - hop))

           (streamOverlapping rate { framesize, hop, window } frames);

    else

        streamOverlapping rate { framesize, hop, window } frames;

    fi);

//!!! todo: this is not yet tested

complexStreamed rate framesize options frames =

   (streamOptions = array [];

    var rowTransform = complex.magnitudes;

    for options \case of

        FrequencyDomain f:

        //!!! what if both f and not-f provided in one options list? need reset

            if f then

                rowTransform := fft.realInverse framesize;

            fi;

        other: push streamOptions other;

    esac;

    transformed = map do c:

        mat.fromRows (map rowTransform (cm.asRows c))

        done frames;

    streamed rate framesize streamOptions transformed);    

typedef opt_t = 

    Hop number | Padded boolean | 

    Window (number -> vec.vector_t) | FrequencyDomain boolean;

{ 

    frames is number -> list?<opt_t> -> stream_t -> list<mat.matrix_t>,

    complexFrames is number -> list?<opt_t> -> stream_t -> list<cm.complexmatrix_t>,

    framesOfFile framesize options filename =

        frames framesize options (af.open filename),

    overlapAdd,

    streamed is number -> number -> list?<opt_t> -> list<mat.matrix_t> -> stream_t,

    complexStreamed is number -> number -> list?<opt_t> -> list<cm.complexmatrix_t> -> stream_t,

}