# doc-cache created by Octave 10.2.0
# name: cache
# type: cell
# rows: 3
# columns: 16
# name: <cell-element>
# type: sq_string
# elements: 1
# length: 8
Contents


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1132
 LTFAT - Block processing

  Zdenek Prusa, 2013 - 2023.

  Basic methods
    BLOCK          - Setup a new block-stream
    BLOCKDEVICES   - List available audio I/O devices
    BLOCKREAD      - Read samples from file/device
    BLOCKPLAY      - Play block (sound output)
    BLOCKPANEL     - Block-stream control GUI
    BLOCKPANELGET  - Obtain parameter(s) from GUI
    BLOCKDONE      - Closes block-stream and frees resources
    BLOCKWRITE     - Appends data to a wav file

  Block-adapted transforms
    BLOCKFRAMEACCEL     - Prepare a frame for a block-stream processing
    BLOCKFRAMEPAIRACCEL - Prepare a pair of frames for a block-stream processing
    BLOCKANA            - Block analysis
    BLOCKSYN            - Block synthesis

  Running visualisation
    BLOCKFIGURE   - Initialize figure for redrawing
    BLOCKPLOT     - Append coefficients to the running plot

  Other
    LTFATPLAY     - Replacement for the sound command allowing selecting an output device

  For help, bug reports, suggestions etc. please visit 
  http://github.com/ltfat/ltfat/issues

   Url: http://ltfat.github.io/doc/blockproc/Contents.html



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 25
 LTFAT - Block processing



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 5
block


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 4146
 -- Function: block
     BLOCK  Initialize block stream
        Usage: block(source);
     
        Input parameters:
           source    : Block stream input.
        Output parameters:
           fs        : Sampling rate.
           classid   : Data type.
     
        BLOCK(source) initializes block data stream from source which
        can be one of the following (the letter-case is ignored for strings):
     
           'file.wav'
              name of a wav file
     
           'dialog'
              shows the file dialog to choose a wav file.
     
           data
              input data as columns of a matrix for each input channel
     
           'rec'
              input is taken from a microphone/auxilary input;
     
           {'rec','file.wav'} or {'rec','dialog'} or {'rec',data}
              does the same as 'rec' but plays a chosen audio data simultaneously.
     
           'playrec'
              loopbacks the input to the output. In this case, the block size
              (in BLOCKREAD) cannot change during the playback.
     
        BLOCK accepts the following optional key-value pairs
     
           'fs',fs
              Required sampling rate - Some devices might support only a 
              limited range of samp. frequencies. Use BLOCKDEVICES to list
              supported sampling rates of individual devices. 
              When the target device does not support the chosen sampling rate,
              on-the-fly resampling will be performed in the background.
              This option overrides sampling rate read from a wav file.
     
              The default value is 44100 Hz, min. 4000 Hz, max. 96000 Hz
     
           'L',L
              Block length - Specifying L fixes the buffer length, which cannot be
              changed in the loop.
     
              The default is 1024. In the online mode the minimum is 32.
     
           'devid',dev
              Whenever more input/output devices are present in your system,
              'devid' can be used to specify one. For the 'playrec' option the
              devId should be a two element vector [playDevid, recDevid]. List
              of the installed devices and their IDs can be obtained by
              BLOCKDEVICES.
     
           'playch',playch
              If device supports more output channels, 'playch' can be used to
              specify which ones should be used. E.g. for two channel device, [1,2]
              can be used to specify channels.
     
           'recch',recch
              If device supports more input channels, 'recch' can be used to
              specify which ones should be used.
     
           'outfile','file.wav'
              Creates a wav file header for on-the-fly storing of block data using
              BLOCKWRITE. Existing file will be overwritten. Only 16bit fixed
              point precision is supported in the files.
     
           'nbuf',nbuf
              Max number of buffers to be preloaded. Helps avoiding glitches but
              increases delay.
     
           'loadind',loadind
              How to show the load indicator. loadind can  be the following:
     
                 'nobar'
                    Suppresses any load display.
     
                 'bar'
                    Displays ascii load bar in command line (Does not work in Octave).
     
                 obj
                    Java object which has a public method updateBar(double).
     
        Optional flag groups (first is default)
     
           'noloop', 'loop'
              Plays the input in a loop.
     
           'single', 'double'
              Data type to be used. In the offline mode (see below) the flag is
              ignored and everything is cast do double.
     
           'online', 'offline'
              Use offline flag for offline blockwise processing of data input or a
              wav file without initializing and using the playrec MEX.
     
     
     *Url*: <http://ltfat.github.io/doc/blockproc/block.html>

     See also: blockread, blockplay, blockana, blocksyn,
     demo_blockproc_basicloop, demo_blockproc_slidingsgram.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 55
BLOCK  Initialize block stream
   Usage: block(source);



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 8
blockana


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1216
 -- Function: blockana
     BLOCKANA Blockwise analysis interface
        Usage: c=blockana(F, f)
     
        Input parameters:
           Fa   : Analysis frame object.    
           f    : Block of signal.
           fola : Explicitly defined overlap
        Output parameters:
           c    : Block coefficients.
           fola : Stored overlap
     
        c=BLOCKANA(Fa,f) calculates the coefficients c of the signal block f using 
        the frame defined by F. The block overlaps are handled according to the 
        F.blokalg. Assuming BLOCKANA is called in the loop only once, fola*
        can be omitted and the overlaps are handled in the background
        automatically.    
     
     
        References:
          N. Holighaus, M. Doerfler, G. A. Velasco, and T. Grill. A framework for
          invertible, real-time constant-Q transforms. IEEE Transactions on
          Audio, Speech and Language Processing, 21(4):775 --785, 2013.
          
          Z. Průša. Segmentwise Discrete Wavelet Transform. PhD thesis, Brno
          University of Technology, Brno, 2012.
          
     *Url*: <http://ltfat.github.io/doc/blockproc/blockana.html>

     See also: block, blocksyn, blockplay.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 64
BLOCKANA Blockwise analysis interface
   Usage: c=blockana(F, f)



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 12
blockdevices


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 376
 -- Function: blockdevices
     BLOCKDEVICES Lists audio devices
        Usage: devs = blockdevices();
     
        BLOCKDEVICES lists the available audio input and output devices. The
        ID can be used in the BLOCK function to specify which device should
        be used.
     
     *Url*: <http://ltfat.github.io/doc/blockproc/blockdevices.html>

     See also: block.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 65
BLOCKDEVICES Lists audio devices
   Usage: devs = blockdevices();



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 9
blockdone


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 510
 -- Function: blockdone
     BLOCKDONE  Destroy the current blockstream
        Usage: blockdone();
     
        BLOCKDONE() closes the current blockstream. The function resets
        the playrec tool and clear all buffers in block_interface.
     
        BLOCKDONE(p1,p2,...) in addition tries to call close methods on
        all input arguments which are JAVA objects (which are passed by reference).
        
     
     *Url*: <http://ltfat.github.io/doc/blockproc/blockdone.html>

     See also: block.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 65
BLOCKDONE  Destroy the current blockstream
   Usage: blockdone();



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 11
blockfigure


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 932
 -- Function: blockfigure
     BLOCKFIGURE Block figure object
        Usage: p=blockfigure();
               p=blockfigure('cm',cmaps);
     
        Output parameters:
              p     : JAVA object of the class net.sourceforge.ltfat.SpectFrame
     
        p=BLOCKFIGURE() initializes a JAVA object for the BLOCKPLOT
        routine. 
     
        Optional key-value pairs:
     
           'cm',cmaps   : Custom colormap (a L x3 matrix) or colormaps
                            (cell array of matrixes).
     
        The function takes in the additional optional arguments:
     
            'location',location:   Window inital position. location
                                     has to be 2 element row vector [x,y]
                                     defining distance from the top-left
                                     corner of the screen. 
     *Url*: <http://ltfat.github.io/doc/blockproc/blockfigure.html>


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
BLOCKFIGURE Block figure object
   Usage: p=blockfigure();
          p=blockf...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 15
blockframeaccel


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1088
 -- Function: blockframeaccel
     BLOCKFRAMEACCEL Precompute structures for block processing
        Usage: F = blockframeaccel(F,Lb);
     
        F=BLOCKFRAMEACCEL(F,Lb) has to be called for each frame object prior to
        entering the main loop where BLOCKANA and BLOCKSYN are called.
        The function works entirely like FRAMEACCEL but in addition, it prepares
        structures for the processing of a consecutive stream of blocks.
     
           'sliwin',sliwin   : Slicing window. sliwin have to be a window
                                 of length 2Lb or a string accepted
                                 by the FIRWIN function. It is used only in
                                 the slicing window approach. The default is 
                                 'hann'.
     
           'zpad',zpad   : Number of zero samples the block will be padded
                             after it is windowed by a slicing window. This
                             does not affect the synthesis windowing.
     *Url*: <http://ltfat.github.io/doc/blockproc/blockframeaccel.html>


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
BLOCKFRAMEACCEL Precompute structures for block processing
   Usage: F = bloc...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 19
blockframepairaccel


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1443
 -- Function: blockframepairaccel
     BLOCKFRAMEPAIRACCEL Precompute structures for block processing
        Usage: F = blockframepairaccel(Fa,Fs,Lb);
     
        [Fao,Fso]=BLOCKFRAMEPAIRACCEL(Fa,Fs,Lb) works similar to 
        BLOCKFRAMEACCEL with a pair of frames. The only difference from
        calling BLOCKFRAMEACCEL separatelly for each frame is correct
        default choice of the slicing windows. Frame objects Fa,Fs will be
        accelerated for length 2*Lb.
     
        The following optional arguments are recognized:
     
           'anasliwin',anasliwin  : Analysis slicing window. sliwin have to
                                      be a window of length 2Lb or a string 
                                      accepted by the FIRWIN function. It is
                                      used only in the slicing window approach.
                                      The default is 'hann'.
     
           'synsliwin',synsliwin  : Synthesis slicing window. The same as the
                                      previous one holds. The default is 'rect'.
     
           'zpad',zpad   : Number of zero samples the block will be padded
                             after it is windowed by a slicing window. Note the
                             frames will be accelerated for length
                             2*Lb+2*kv.zpad. 
     
     *Url*:
     <http://ltfat.github.io/doc/blockproc/blockframepairaccel.html>


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
BLOCKFRAMEPAIRACCEL Precompute structures for block processing
   Usage: F = ...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 10
blockpanel


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1076
 -- Function: blockpanel
     BLOCKPANEL Control panel
        Usage: blockpanel(params)
     
        Input parameters:
           params: Cell-array of parameters specifications.
     
        Output parameters:
           p : Control panel Java object
     
        BLOCKPANEL(params) creates a Java object containing GUI for changing
        parameters during the playback. params should be a cell-array, whose 
        elements are another cell array of the following format:
     
           {'var','label',minVal,maxVal,defVal,valCount}
     
        Example:
     
        params = {
                    {'G','Gain',-20,20,0,21}
                 }
      
        The function takes in the additional optional arguments:
     
            'location',location:   Window initial position. location
                                     has to be 2 element row vector [x,y]
                                     defining distance from the top-left
                                     corner of the screen. 
     *Url*: <http://ltfat.github.io/doc/blockproc/blockpanel.html>


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 53
BLOCKPANEL Control panel
   Usage: blockpanel(params)



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 13
blockpanelget


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 954
 -- Function: blockpanelget
     BLOCKPANELGET Get parameters from GUI
        Usage: [par,...] = blockpanelget(p,spar,...)
     
        Input parameters:
              p    : JAVA object
              spar : String. Name of the parameter.
     
        Output parameters:
              par  : Single value or vector of parameters.
     
        par = BLOCKPANELGET(p,'spar') gets a current value of the parameter
        'spar' from the GUI specified in p. 
        par = BLOCKPANELGET(p,'spar1','spar2','spar3') gets current values
        of the parameters 'spar1', 'spar2' and 'spar3' from the GUI and
        stores them in a vector p.
        [par1,par2,par3] = BLOCKPANELGET(p,'spar1','spar2','spar3') gets 
        current values of the parameters 'spar1', 'spar2' and 'spar3' 
        from the GUI and stores them in the separate variables par1,par2
        and par3. 
     
     *Url*: <http://ltfat.github.io/doc/blockproc/blockpanelget.html>


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
BLOCKPANELGET Get parameters from GUI
   Usage: [par,...] = blockpanelget(p,s...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 9
blockplay


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 550
 -- Function: blockplay
     BLOCKPLAY Schedules block to be played
        Usage: blockplay(L)
            
        Input parameters:
           f    : Samples.
     
        Function schedules samples in f to be played. Since playrec handles
        playing and recording in a single command, the actual relay of samples
        to playrec is done in the next call of BLOCKREAD.
        In case no audio output is expected (in the rec only mode), 
        the function does nothing.
     *Url*: <http://ltfat.github.io/doc/blockproc/blockplay.html>


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
BLOCKPLAY Schedules block to be played
   Usage: blockplay(L)
       
   Inpu...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 9
blockplot


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1385
 -- Function: blockplot
     BLOCKPLOT Plot block coefficients
        Usage: blockplot(p,c);
               blockplot(p,F,c);
               blockplot(p,F,c,cola);
     
        Input parameters:
              p     : JAVA object of the class net.sourceforge.ltfat.SpectFrame.
              F     : Frame object.
              c     : Block coefficients.
              cola  : (Optional) overlap from previous block.
     
        Output parameters:
              cola  : Overlap to the next block.
     
        BLOCKPLOT(p,F,c) appends the block coefficients c to the running 
        coefficient plot in p. The coefficients must have been obtained by
        c=blockana(F,...). The format of c is changed to a rectangular 
        layout according to the type of F. p must be a Java object with a
        append method.  
     
        cola=BLOCKPLOT(p,F,c,cola) does the same, but adds cola to the 
        first respective coefficients in c and returns last coefficients from
        c. This is only relevant for the sliced window blocking approach.
     
        BLOCKPLOT(p,c) or BLOCKPLOT(p,[],c) does the same, but expects c 
        to be already formatted matrix of real numbers. The data dimensions
        are not restricted, but it will be shrinked or expanded to fit with
        the running plot.
     
     *Url*: <http://ltfat.github.io/doc/blockproc/blockplot.html>


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
BLOCKPLOT Plot block coefficients
   Usage: blockplot(p,c);
          blockpl...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 9
blockread


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 985
 -- Function: blockread
     BLOCKREAD Read one block from input
        Usage: f=blockread(L)
            
        Input parameters:
           L    : Number of samples.
        Output parameters:
           f     : Samples.
           valid : Input data valid flag.
     
        f=BLOCKREAD(L) reads next L audio samples according to source 
        specified in BLOCK. f is a LxW matrix, where columns are
        channels in the stream. 
     
        [f,valid]=blockrad(...) does the same and in addition it returns valid*
        flag, which is set to 1, except for the last block of the stream (e.g.
        at the end of a file).
     
        Function also control the playback, so it does not have to rely on
        whether the user called BLOCKPLAY.
      
        Block streaming uses several buffers to compensate for the processing
        delay variation. 
     
     
     *Url*: <http://ltfat.github.io/doc/blockproc/blockread.html>

     See also: block, blockplay.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
BLOCKREAD Read one block from input
   Usage: f=blockread(L)
       
   Input...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 8
blocksyn


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1601
 -- Function: blocksyn
     BLOCKSYN Blockwise synthesis interface
        Usage: blocksyn(F, c, Lb)
     
        Input parameters:
           F    : Synthesis frame object.
           c    : Coefficients of a block.
           Lb   : Length of the block.
           fola : Explicitly defined overlap.
        Output parameters:
           fhat : Reconstructed block of signal.
           fola : Stored overlap.
     
        fhat=BLOCKSYN(F,c,Lb) reconstructs the signal block fhat from the
        coefficients c using the frame defined by F. If some overlap is used,
        it is stored internally using block_interface. Note that the function is 
        capable of handling overlaps internally only for a single call
        to the function in the blockproc. loop.%   
     
        [fhat,fola]=BLOCKSYN(F,c,Lb,fola) does the same, but the block algorithm
        uses fola to read and store overlap explicitly. fola can be empty.
     
        *Note:* To get perfect reconstruction, the synthesis frame F must
        be a dual frame of the analysis frame used in BLOCKANA.
     
     
        References:
          N. Holighaus, M. Doerfler, G. A. Velasco, and T. Grill. A framework for
          invertible, real-time constant-Q transforms. IEEE Transactions on
          Audio, Speech and Language Processing, 21(4):775 --785, 2013.
          
          Z. Průša. Segmentwise Discrete Wavelet Transform. PhD thesis, Brno
          University of Technology, Brno, 2012.
          
     *Url*: <http://ltfat.github.io/doc/blockproc/blocksyn.html>

     See also: block, blockana, framedual.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 67
BLOCKSYN Blockwise synthesis interface
   Usage: blocksyn(F, c, Lb)



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 10
blockwrite


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 582
 -- Function: blockwrite
     BLOCKWRITE  Append block to an existing file
        Usage: blockwrite(f);
     
        Input parameters:
           f    : Block stream input.
     
        Function appends f to a existing file. The file must have been
        explicitly defined as the 'outfile' parameter of BLOCK prior
        calling this function. If not, the function does nothing.
     
        The function expect exactly the same format of f as is returned by
        BLOCKREAD.
     
     *Url*: <http://ltfat.github.io/doc/blockproc/blockwrite.html>

     See also: block.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 69
BLOCKWRITE  Append block to an existing file
   Usage: blockwrite(f);



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 9
ltfatplay


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1340
 -- Function: ltfatplay
     LTFATPLAY Play data samples or a wav file
        Usage: ltfatplay('file.wav')
               ltfatplay(data,'fs',fs)
               ltfatplay(...,'devid',devid)
     
     
        LTFATPLAY('file.wav') plays a wav file using the default sound device.
     
        LTFATPLAY('file.wav','devid',devid) plays a wav file using the sound
        device with id devid. A list of available devices can be obtained by 
        BLOCKDEVICES.
     
        LTFATPLAY(data,'fs',fs,...) works entirely similar, but data is
        expected to be a vector of length L or a LxW matrix with
        columns as individual channels and fs to be a sampling rate to be used.
        When no sampling rate is specified, 44.1 kHz is used.
     
        In addition, individual channels of the output sound device can be
        selected by using an additional key-value pair
     
        'playch',playch
           A vector of channel indexes starting at 1.
     
        This function has the advantage over sound and soundsc that one can 
        directly specify output device chosen from BLOCKDEVICES. Similar
        behavior can be achieved using audioplayer and audiodevinfo but
        only in Matlab. Audioplayer is not yet supported in Octave.
        
     *Url*: <http://ltfat.github.io/doc/blockproc/ltfatplay.html>


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
LTFATPLAY Play data samples or a wav file
   Usage: ltfatplay('file.wav')
   ...





