./../../src/sndfile-palette.lsp

## palette/sndfile-palette [ Classes ]

[ Top ] [ palette ] [ Classes ]

NAME

     sndfile-palette

     File:             sndfile-palette.lsp

     Class Hierarchy:  named-object -> linked-named-object -> sclist ->
                       circular-sclist -> assoc-list -> recursive-assoc-list ->
                       palette -> sndfile-palette

     Version:          1.0.3

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Implementation of the sndfile-palette class, which is a
                       simple palette that checks that all the sound files given
                       in a list for each id exist.  See comments in methods for
                       limitations and special features of this class.

     Author:           Michael Edwards: m@michael-edwards.org

     Creation date:    18th March 2001

     $$ Last modified: 13:57:04 Wed Jun 12 2013 BST

     SVN ID: $Id: sndfile-palette.lsp 3940 2013-06-19 10:04:04Z medward2 $

## sndfile-palette/analyse-followers [ Methods ]

[ Top ] [ sndfile-palette ] [ Methods ]

DESCRIPTION

     Using the followers slots of each sndfile in the palette, go through each
     sndfile in the palette and generate a large number of following sounds,
     i.e. emulate the max-play.  The results of the follow-on process are then
     analysed and a warning will be issued if any sndfile seems to dominate
     (defined as being present at least twice as many times as its 'fair share',
     where 'fair share' would mean an even spread for all the sound files in the
     palette).

ARGUMENTS

     - The sndfile-palette object.

OPTIONAL ARGUMENTS

     How many times to repeat the generation process.  Default = 1000.

RETURN VALUE

     T or NIL depending on whether the analysis detects an even spread or not.

SYNOPSIS

    (defmethod analyse-followers ((sfp sndfile-palette) &optional (depth 1000))

## sndfile-palette/auto-cue-nums [ Methods ]

[ Top ] [ sndfile-palette ] [ Methods ]

DESCRIPTION

     Set the cue-num slot of every sndfile-ext object in the palette to be an
     ascending integer starting at 2. NB If a sndfile has it's :use slot set to
     NIL it won't be given a cue number.

ARGUMENTS

     - a sndfile-palette object.

RETURN VALUE

     The cue number of the last sndfile-ext object.

SYNOPSIS

    (defmethod auto-cue-nums ((sfp sndfile-palette))

## sndfile-palette/find-sndfile [ Methods ]

[ Top ] [ sndfile-palette ] [ Methods ]

DESCRIPTION

     Return the full directory path and file name of a specified sound file,
     from within the directories given in the PATHS slot.

ARGUMENTS

     - A sndfile-palette object.
     - The name of a sound file from within that object. This can be a string or
       a symbol. Unless it is given as a string, it will be handled as a symbol
       and will be converted to lowercase. Inclusion of the file extension is
       optional.

RETURN VALUE

     Returns the full directory path and file name of the specified sound file
     as a string.

EXAMPLE

    (let ((msfp (make-sfp 'sfp-test
                          '((sndfile-group-1
                             (test-sndfile-1))
                            (sndfile-group-2
                             (test-sndfile-2 test-sndfile-3
                              (test-sndfile-4 :frequency 261.61)))
                            (sndfile-group-3
                             ((test-sndfile-5 :start 0.006 :end 0.182)
                              test-sndfile-6)))
                          :paths
                          '("/path/to/sndfiles-dir-1"
                            "/path/to/sndfiles-dir-2"))))
     (find-sndfile msfp 'test-sndfile-4))

    => "/path/to/sndfiles-dir-2/test-sndfile-4.aiff"

SYNOPSIS

    (defmethod find-sndfile ((sfp sndfile-palette) sndfile)

## sndfile-palette/get-snd-with-cue-num [ Methods ]

[ Top ] [ sndfile-palette ] [ Methods ]

DESCRIPTION

     Return the (first, but generally unique) sndfile object which has the
     given cue-num slot.

ARGUMENTS

     - the sndfile-palette object.
     - the cue number (integer).

RETURN VALUE

     The sndfile/sndfile-ext object with the given cue number or NIL if it can't
     be found.

SYNOPSIS

    (defmethod get-snd-with-cue-num ((sfp sndfile-palette) cue-num)

## sndfile-palette/make-sfp [ Functions ]

[ Top ] [ sndfile-palette ] [ Functions ]

DESCRIPTION

     Make a sndfile-palette object. This object is a simple palette which checks
     to make sure that all of the sound files in a given list exist for each
     given ID.

     Sound files are given as as single names, without the path and without the
     extension. These can be given using the optional keyword arguments <paths>
     and <extensions>.

     NB Although this class is a palette and therefore a subclass of
     recursive-assoc-list, the sound lists in this case cannot be nested beyond
     a depth of two (as in example below).

ARGUMENTS

     - An ID for the palette.
     - A list of lists that contains IDs for the names of one or more groups of
       sound files, each paired with a list of one or more names of existing
       sound files. The sound file names themselves can be paired with keywords
       from the sndfile class, such as :start, :end, and :frequency, to define
       and describe segments of a given sound file.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :paths. A list of one or more paths to where the sound files are located.
     - :extensions. A list of one or more sound file extensions for the
       specified sound files. The default initialization for this slot of the
       sndfile-palette already contains ("wav" "aiff" "aif" "snd"), so this
       argument can often be left unspecified.
     - :warn-not-found. T or NIL to indicate whether a warning should be printed
       to the Lisp listener if the specified sound file cannot be found.
       T = print warning. Default = T.

RETURN VALUE

     Returns NIL.

EXAMPLE

    (let ((msfp (make-sfp 'sfp-test
                          '((sndfile-group-1
                             (test-sndfile-1))
                            (sndfile-group-2
                             (test-sndfile-2 test-sndfile-3
                              (test-sndfile-4 :frequency 261.61)))
                            (sndfile-group-3
                             ((test-sndfile-5 :start 0.006 :end 0.182)
                              test-sndfile-6)))
                          :paths '("/path/to/sound-files-dir-1/"
                                   "/path/to/sound-files-dir-2/")))))

SYNOPSIS

    (defun make-sfp (id sfp &key paths (extensions '("wav" "aiff" "aif" "snd"))
                     with-followers (warn-not-found t))

## sndfile-palette/make-sfp-from-groups-in-wavelab-marker-file [ Functions ]

[ Top ] [ sndfile-palette ] [ Functions ]

DESCRIPTION

     Automatically generate a sndfile-palette object using the specified sound
     file from grouping defined in the specified wavelab marker file.

     The <marker-file> argument can be passed as a list of marker files, in
     which case these will first be concatenated.

ARGUMENTS

     - A string that is the name of the marker file, including the directory
       path and extension.
     - A string that is the name of the sound file. This can either be a full
       directory path, file name, and extension, or just a base file name. If
       the latter, values for the optional arguments :paths and :extensions must
       also be specified.

OPTIONAL ARGUMENTS

     - :paths. NIL or a list of strings that are the directory paths to the
       specified sound files. If the sound file is passed with the directory
       path, this must be set to NIL. NB: The paths given here apply only to the
       sound files, not to the marker files. Default = NIL.
     - :extensions. A list of strings that are the extensions to the given sound
       files. If the sound files are passed with their extensions, this must be
       set to NIL. Default = NIL.
     - :warn-not-found. T or NIL to indicate whether to print a warning to the
       listener if the specified sound file is not found. T = print a
       warning. Default = NIL.
     - :sampling-rate. An integer that is the sampling rate of the specified
       sound file. Changing this value will alter the start-times determined for
       each sound segment. Default = 44100.
     - :print. T or NIL to indicate whether feedback about the groups found and
       created should be printed to the listener. T = print. Default = T.

RETURN VALUE

     Returns NIL.

EXAMPLE

    (make-sfp-from-groups-in-wavelab-marker-file
     "/path/to/24-7.mrk"
     "24-7"
     :paths '("/path/to/sndfile/directory/")
     :sampling-rate 44100
     :extensions '("wav"))

    =>
    24 markers read from /path/to/24-7.mrk
    Adding tapping: 2.753 -> 4.827
    Adding tapping: 5.097 -> 6.581
    Adding tapping: 6.763 -> 8.538
    Adding splinter: 13.878 -> 15.993
    Adding tapping: 16.338 -> 18.261
    Adding splinter: 19.403 -> 25.655

    tapping: 4 sounds
    splinter: 2 sounds

SYNOPSIS

    (defun make-sfp-from-groups-in-wavelab-marker-file (marker-file sndfile
                                                        &key
                                                        paths
                                                        extensions
                                                        warn-not-found
                                                        (sampling-rate 44100)
                                                        (print t))

## sndfile-palette/make-sfp-from-wavelab-marker-file [ Functions ]

[ Top ] [ sndfile-palette ] [ Functions ]

DESCRIPTION

     Automatically create a sndfile-palette object from the specified wavelab
     marker file and the specified sound file (from which the marker file must
     have been generated).

     The function will produce a sndfile-palette object with multiple groups,
     each of which consists of the number of sound file segments specified using
     the :snds-per-group argument (defaults to 8). By default the segments will
     be collected into the groups in chronological order. If the optional
     :random-every argument is given a value, every nth group will consist of
     random segments instead.

     The sound file segments of each group will correspond to the time points
     stored in the marker file.

     The <marker-file> argument can consist of a list of marker files, in which
     case these would first be concatenated.

     NB: Be aware that marker files created on operating systems differing from
         the one on which this function is called might trigger errors due to
         newline character mismatches.

ARGUMENTS

     - A string that is the name of the marker file, including the directory
       path and extension.
     - A string that is the name of the sound file. This can either be a full
       directory path, file name, and extension, or just a base file name. If
       the latter, values for the optional arguments :paths and :extensions must
       also be specified.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :snds-per-group. An integer that is the number of sound file segments to
       include in each group. Default = 8.
     - :random-every. An integer to indicate that every nth group is to consist
       of random (rather than chronologically consecutive) sound file segments.
       Default = 999999 (i.e. essentially never)
     - :paths. NIL or a list of strings that are the directory paths to the
       specified sound files. If the sound file is passed with the directory
       path, this must be set to NIL. NB: The paths given here apply only to the
       sound files, not to the marker files. Default = NIL.
     - :sampling-rate. An integer that is the sampling rate of the specified
       sound file. Changing this value will alter the start-times determined for
       each sound segment. Default = 44100.
     - :extensions. A list of strings that are the extensions to the given sound
       files. If the sound files are passed with their extensions, this must be
       set to NIL. Default = NIL.
     - :warn-not-found. T or NIL to indicate whether to print a warning to the
       listener if the specified sound file is not found. T = print a
       warning. Default = NIL.
     - :name. The name for the overall sndfile-palette and the base name for
        each group within (these will have a suffix that is an auto-incrementing
        number e.g. 'auto would become 'auto1 'auto2 etc.).  Default = 'auto.

RETURN VALUE

     A sndfile-palette object.

EXAMPLE

    (make-sfp-from-wavelab-marker-file
      "/path/to/24-7.mrk"
     "24-7"
     :snds-per-group 2
     :random-every 3
     :paths '("/path/to/sound-file/directory/")
     :sampling-rate 44100
     :extensions '("wav"))

    =>
    SNDFILE-PALETTE: paths: (/Volumes/JIMMY/SlipperyChicken/sc/test-suite/)
                     extensions: (wav)
    PALETTE:
    RECURSIVE-ASSOC-LIST: recurse-simple-data: T
                          num-data: 8
                          linked: NIL
                          full-ref: NIL
    ASSOC-LIST: warn-not-found NIL
    CIRCULAR-SCLIST: current 0
    SCLIST: sclist-length: 8, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: AUTO, tag: NIL,
    data: (
    NAMED-OBJECT: id: "auto1", tag: NIL,
    data: (

    SNDFILE: path: /Volumes/JIMMY/SlipperyChicken/sc/test-suite/24-7.wav,
             snd-duration: 29.652811, channels: 2, frequency: 261.62555
             start: 0.09142857, end: 1.0361905, amplitude: 1.0, duration 0.94476193
             will-be-used: 0, has-been-used: 0
             data-consistent: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: "24-7", tag: NIL,
    data: /Volumes/JIMMY/SlipperyChicken/sc/test-suite/24-7.wav
    [...]

SYNOPSIS

    (defun make-sfp-from-wavelab-marker-file (marker-file sndfile
                                              &key
                                              (snds-per-group 8)
                                              (random-every 999999) ;; i.e. never
                                              paths
                                              (sampling-rate 44100)
                                              extensions
                                              ;; MDE Fri Oct  5 14:04:08 2012
                                              (name 'auto)
                                              warn-not-found)

## sndfile-palette/max-play [ Methods ]

[ Top ] [ sndfile-palette ] [ Methods ]

DESCRIPTION

     This generates the data necessary to play the next sound in the current
     sound's followers list.  See the sndfile-ext method for details.

ARGUMENTS

     - The sndfile-palette object.
     - The fade (in/out) duration in seconds.
     - The maximum loop duration in seconds.
     - The time to trigger the next file, as a percentage of the current
       sndfile-ext's duration.

OPTIONAL ARGUMENTS

     - whether to print data to the listener as it is generated. Default = NIL.

RETURN VALUE

     A list of values returned by the sndfile-ext method.

SYNOPSIS

    (defmethod max-play ((sfp sndfile-palette) fade-dur max-loop start-next
                         &optional print)

## sndfile-palette/osc-send-cue-nums [ Methods ]

[ Top ] [ sndfile-palette ] [ Methods ]

DESCRIPTION

     Send via OSC the cue number of each sound file in a form that a Max sflist~
     can process and store.

ARGUMENTS

     - the sndfile-palette object.

RETURN VALUE

     The number of cue numbers sent.  NB This is not the same as the last cue
     number as cues start from 2.

SYNOPSIS

    (defmethod osc-send-cue-nums ((sfp sndfile-palette))

## sndfile-palette/reset [ Methods ]

[ Top ] [ sndfile-palette ] [ Methods ]

DESCRIPTION

     Reset the followers' slot circular list to the beginning or to <where>

ARGUMENTS

     - the sndfile-palette object.

OPTIONAL ARGUMENTS

     - an integer to set the point at which to restart.  This can be higher than
       the number of followers as it will wrap.  Default = nil (which equates to
       0 lower down in the class hierarchy).
     - whether to issue a warning if <where> is greater than the number of
       followers (i.e. that wrapping will occur).  Default = T.

RETURN VALUE

     T

SYNOPSIS

    (defmethod reset ((sfp sndfile-palette) &optional where (warn t))