./../../src/sndfile-ext.lsp

## sndfile-ext/get-next [ Methods ]

[ Top ] [ sndfile-ext ] [ Methods ]

DESCRIPTION

     Get the next sound file from the <followers> slot.

ARGUMENTS

     - A sndfile-ext object.

RETURN VALUE

     A sndfile-ext object.

SYNOPSIS

    (defmethod get-next ((sfe sndfile-ext))

## sndfile-ext/make-sndfile-ext [ Functions ]

[ Top ] [ sndfile-ext ] [ Functions ]

DESCRIPTION

     Make a sndfile-ext (extension of sndfile) object which holds the usual
     sndfile data as well as a host of others to do with the characteristics of
     the sound file.  In addition, the followers slot specifies sound files
     which can follow the current one.  The bitrate, srate, num-frames, and
     bytes slots will be filled automatically if the path to an existing sound
     file is given.

ARGUMENTS

     See defclass slot descriptions

RETURN VALUE

     A sndfile-ext object or NIL if path is NIL

SYNOPSIS

    (defun make-sndfile-ext (path &key id data duration end (start 0.0)
                                    (frequency nil) (amplitude 1.0) (cue-num -1)
                                    (use t) (pitch -1) (pitch-curve -1) (bandwidth -1)
                                    (bandwidth-curve -1) (continuity -1)
                                    (continuity-curve -1) (weight -1) (weight-curve -1)
                                    (energy -1) (energy-curve -1) (harmonicity -1)
                                    (harmonicity-curve -1) (volume -1)
                                    (volume-curve -1) (loop-it nil) (bitrate -1)
                                    (srate -1) (num-frames -1)
                                    (bytes -1) followers group-id)

## sndfile-ext/max-cue [ Methods ]

[ Top ] [ sndfile-ext ] [ Methods ]

DESCRIPTION

     Generate the data necessary to preload the sound file in a MaxMSP sflist~
     object.

ARGUMENTS

     - The sndfile-ext object.

OPTIONAL ARGUMENTS

     - Whether to issue an error if the cue-num slot has not been set to a value
       above 1.  Default = #'error.  Could also be #'warn and NIL.

RETURN VALUE

     A list of data suitable to be passed via OSC to the sflist~ object.

EXAMPLE

    (let* ((sf1 (make-sndfile-ext
                 (concatenate 'string
                              cl-user::+slippery-chicken-home-dir+
                              "test-suite/sndfile-1.aiff")
                 :cue-num 2 :start 0.3 :end 1.1 :frequency 653)))
      (max-cue sf1))

    =>
    ("preload" 2 "/Users/medward2/lisp/sc/test-suite/sndfile-1.aiff" 300.0 1100.0)

SYNOPSIS

    (defmethod max-cue ((sfe sndfile-ext) &optional (on-fail #'error))

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

[ Top ] [ sndfile-ext ] [ Methods ]

DESCRIPTION

     Generate the data necessary for MaxMSP to play the sndfile using the
     sflist~ and sfplay~.

     NB fade-dur could be 0 (= no fade)

ARGUMENTS

     - The sndfile-ext 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.

RETURN VALUE

     A list of values to be passed via OSC to sndfilenet-aux.maxpat:
     cue-number number-of-channels loop speed fade-dururation
     fade-out-start-time delay-to-next-snfile-start amplitude

EXAMPLE

    (let* ((sf1 (make-sndfile-ext
                 (concatenate 'string
                              cl-user::+slippery-chicken-home-dir+
                              "test-suite/sndfile-1.aiff")
                 :start 0.3 :end 1.1 :frequency 653)))
      (max-play sf1 20))

    =>
    (-1 1 0 1.0 0.32000002 0.48)

SYNOPSIS

    (defmethod max-play ((sfe sndfile-ext) fade-dur max-loop start-next
                         &optional ignore)

## sndfile-ext/proximity [ Methods ]

[ Top ] [ sndfile-ext ] [ Methods ]

DESCRIPTION

     In terms of the characteristics expressed in the various class slots,
     evaluate the proximity of one sndfile-ext object to another.  The closer
     they are in character, the closer to 0 the returned value will be.  The
     order of the two sndfile-ext objects passed to the method is unimportant as
     the return value is always >= 0.0.  The more slots match, the lower
     (closer) the result will be, i.e., slots are only compared if they have a
     value >= 0 (they default to -1), so it could be that in one comparison 5/6
     slots match exactly, and in another 2/3 match; in both cases the
     non-matching slots is off by 1; in that case the first comparison will
     return a lower value: 0.067 vs 0.233.

ARGUMENTS

     - first sndile-ext object
     - second sndile-ext object

RETURN VALUE

     A floating point number >= 0.0 where 0.0 indicates an exact match.

EXAMPLE

    (let ((sf3 (make-sndfile-ext
                nil :pitch 3 :pitch-curve 4 :bandwidth 10 :energy 2
                :harmonicity-curve 0))
          (sf4 (make-sndfile-ext
                nil :pitch 3 :pitch-curve 4 :bandwidth 10 :energy 2
                :harmonicity-curve 1)))
      ;; harmonicity-curve is slightly different so we get a result > 0
      (print (proximity sf3 sf4))
      (set-characteristic sf4 'harmonicity-curve 0)
      ;; now they're the same so we get 0.0
      (proximity sf3 sf4))

    =>
    0.12857144
    0.0

SYNOPSIS

    (defmethod proximity ((sfe1 sndfile-ext) (sfe2 sndfile-ext))

## sndfile-ext/reset [ Methods ]

[ Top ] [ sndfile-ext ] [ Methods ]

DESCRIPTION

     Reset the <followers> circular list to the first or any other following
     sound file.

ARGUMENTS

     A sndfile-ext object.

OPTIONAL ARGUMENTS

     The position (index) to reset to (will default to 0 i.e. the beginning of
     the list).  NB This position may be higher than the number of followers
     attached to any given sndfile-ext object as it will wrap around.

RETURN VALUE

     T

SYNOPSIS

    (defmethod reset ((sfe sndfile-ext) &optional where (warn t))

## sndfile-ext/set-characteristic [ Methods ]

[ Top ] [ sndfile-ext ] [ Methods ]

DESCRIPTION

     Set the chracteristic of a sndfile-ext object to a given value.  The value
     for the slot is first checked to correspond to an accepted range; if not an
     error (default) or warning (or nothing) will be issued.

ARGUMENTS

     - a sndfile-ext object.
     - the characteristic, i.e. one of the class slot names, as a symbol.
     - the new value, as an accepted integer (see characteristics slot for
       accepted range).

OPTIONAL ARGUMENTS

     - the function to call if the given value is out of range. Default =
     #'error but could also be #'warn, or NIL (if no error message should be
     issued).

RETURN VALUE

     NIL on fail otherwise <value>

EXAMPLE

    (let ((sf4 (make-sndfile-ext
                nil :pitch 3 :pitch-curve 4 :bandwidth 10 :energy 2
                :harmonicity-curve 1)))
      ;; out of range but no error/warning
      (print (set-characteristic sf4 'harmonicity-curve 15 nil))
      ;; out of range and warn
      (print (set-characteristic sf4 'harmonicity-curve -1 #'warn))
      ;; in range
      (set-characteristic sf4 'harmonicity-curve 0))

    =>
    NIL
    WARNING:
       sndfile-ext::set-characteristic: No such characteristic: HARMONICITY-CURVE -1
    NIL
    0

SYNOPSIS

    (defmethod set-characteristic ((sfe sndfile-ext) characteristic value
                                   &optional (on-fail #'error))

## sndfile/sndfile-ext [ Classes ]

[ Top ] [ sndfile ] [ Classes ]

NAME

     sndfile-ext

     File:             sndfile-ext.lsp

     Class Hierarchy:  named-object -> linked-named-object -> sndfile ->
                       sndfile-ext

     Version:          1.0.10

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Extension of the sndfile class to hold further properties
                       which quantify the character of the sound file, and
                       specifies sound files which can follow the current one.
                       Specifically created to interface with the sndfilenet
                       project in MaxMSP via OSC (see osc.lsp and osc-sc.lsp).

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

     Creation date:    16th December 2012, Koh Mak, Thailand

     $$ Last modified:  18:43:20 Fri Dec 21 2018 CET

     SVN ID: $Id$