linked-named-object/sndfile [ Classes ]

[ Top ] [ linked-named-object ] [ Classes ]

NAME

 sndfile

 File:             sndfile.lsp

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

 Version:          1.1.0

 Project:          slippery chicken (algorithmic composition)

 Purpose:          Implementation of the sndfile class that holds
                   information about a sound file as well as specifying
                   desired parameters

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

 Creation date:    March 21st 2001

 $$ Last modified:  10:02:08 Mon Jun 24 2024 CEST

sndfile/centroid [ Methods ]

[ Top ] [ sndfile ] [ Methods ]

DATE

 February 7th 2023, Heidhausen

DESCRIPTION

 Calculate the average spectral centroid of a sound file, between the start
 and end points given. This requires CLM's scentroid.ins to be compiled
 and loaded in advance. Note that the averaging is done by FFT analysis every
 10 milliseconds and with an FFT size of 4096 samples. FFT frames that have
 an RMS amplitude of < -40dbFS will be ignored.

ARGUMENTS

 the sndfile object

RETURN VALUE

 The frequency of the centroid in Hertz.

SYNOPSIS

(defmethod centroid ((sf sndfile))

sndfile/get-sound-info [ Functions ]

[ Top ] [ sndfile ] [ Functions ]

AUTHOR

 Leon Focker: leon@leonfocker.de

DATE

 March 17th 2024.

DESCRIPTION

 Get duration, srate, number of channels and bits per sample for a
 sound (or video) file. This function uses clm, if installed, or ffprobe
 as an alternative and fallback method, when clm is not available.
 Use (set-sc-config 'ffprobe-command "new/path") to change the default path
 for ffprobe.

 NB: CLM is not recommended for use with video files.

ARGUMENTS

 - filename. The path to the sound or video file.

OPTIONAL ARGUMENTS

 - ffprobe. Default=nil. When nil, use clm if possible, else ffprobe.
   When t, use ffprobe with the default path to ffprobe. When a string,
   interpret that string as path to the ffprobe executable.

RETURN VALUE

 a list containing srate, number of channels, bits per sample, duration, 
 the file size in byte, the number of framples, the video fps, width and
 heigth as numbers.

SYNOPSIS

(defun get-sound-info (filename &optional ffprobe)

sndfile/make-sndfile [ Functions ]

[ Top ] [ sndfile ] [ Functions ]

DESCRIPTION

 Create a sndfile object to hold data about an existing sound file,
 specifying at least the path and file name of that sound file. Optional
 arguments allow for the specification of segments within the given sound
 file and its perceived fundamental frequency (for src-based
 transposition). 

 If the first argument ("path") is a list, then this sndfile object has been
 created from within a sndfile-palette object. In this case, the first item
 in the list will be the full path to the sound file, as defined in the
 sndfile-palette object; the second item in the list is the list given by
 the user containing the data slots to be used, whereby the first item of
 that list must be the ID of the object.

 NB: This function creates an object of the class sndfile, which is contains
     data concerning an existing sound file. It does not create an actual
     sound file. 

ARGUMENTS

 - A path and file name of an existing sound file; or a list as explained
   above. 

OPTIONAL ARGUMENTS

 keyword arguments:
 - :id. An ID for the sndfile. Will be set automatically if created from
   within a sndfile-palette.  Default nil.
 - :data. The given file name, including path and extension, usually set
   automatically to be the given path if nil.  Default nil. 
 - :duration. A number in seconds which is the duration of the segment of
   the specified sound file which the user would like to use. This should
   not be specified if :end has been specified. Default nil.
 - :end. A number in seconds which is the end time within the source sound
   file for the segment of the file which the user would like to use. This
   should not be specified if :duration has been specified. Default nil.
 - :start. A number in seconds which is the start time within the source
   sound file for the segment of the file which the user would like to
   use. Defaults to 0.0.
 - :frequency. A number or note-name symbol. This frequency will serve as
   the reference pitch for any src transpositions of this file. This can be
   any value, but will most likely be specified if the source sound file has
   a perceptible fundamental pitch. If given as a number, this number will
   be handled as a frequency in Hertz. Default = 'C4.
 - :amplitude. An number that is the amplitude which the user would like to
   designate for this sound file. This number may be of any value, as
   slippery chicken normalizes all sound file events; however, standard
   practice would suggest that this should fall between 0.0 and 1.0.
   Default = 1.0
 - :angle-env. used for spatialization, fore example with
   #'write-reaper-ambisonics-file. Can be an env (list of breakpoints) or
   a list of envs. A list of envs can be used to spatialize different
   channels of the soundfile differently. See the examples in
   write-reaper-ambisonics-file. This then represents the azimuth angle in a
   polar coordinate system. 0 and 1 represend 0° and 360° and are assumed to 
   be in the front. 0.5 would thus be 180° and located behind the listener.
 - :elevation-env. same as angle-env but represents the elevation angle.
   (the horizontal angle from the x-axis). -.5 represents the lowest point
   at -90°, 0 the level of the listening position and .5 the top (90°).
   This is, so that the span from 0 to 1 can represent the entire 360°.
 - :distance-env. same as angle-env but represents the distance from the
   listening position. This is not really relevant for use in ambisonics.
   There the distance is usually 1.

RETURN VALUE

 A sndfile object.

EXAMPLE

;; Example specifying the full path, a start and end time, and a base frequency 
(make-sndfile "/path/to/sndfile-1.aiff"
              :start 0.3
              :end 1.1
              :frequency 654)

=> 

SNDFILE: path: /path/to/sndfile-1.aiff, 
         snd-duration: 3.011043, channels: 1, frequency: 654
         start: 0.3, end: 1.1, amplitude: 1.0, duration 0.8
         will-be-used: 0, has-been-used: 0
         data-consistent: T
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: NIL, tag: NIL, 
data: /path/to/sndfile-1.aiff

;; Example using the sndfile-palette list as the first argument
(make-sndfile '("/path/to/sndfile-1.aiff" 
                (nil :start 0.3 :end 1.1)))

=> 

SNDFILE: path: /path/to/sndfile-1.aiff, 
         snd-duration: 3.011043, channels: 1, frequency: 261.62555
         start: 0.3, end: 1.1, amplitude: 1.0, duration 0.8
         will-be-used: 0, has-been-used: 0
         data-consistent: T
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: "/Volumes/JIMMY/SlipperyChicken/sndfile-2.aiff", tag: NIL, 
data: /path/to/sndfile-1.aiff

SYNOPSIS

(defun make-sndfile (path &key id data duration end (start 0.0)
                          (force-ffprobe nil)
                          (frequency nil)
                          (amplitude 1.0)
                          (angle-env '(0 0  100 0))
                          (elevation-env '(0 0  100 0))
                          (distance-env '(0 1  100 1)))

sndfile/reset-usage [ Methods ]

[ Top ] [ sndfile ] [ Methods ]

DESCRIPTION

 Reset the WILL-BE-USED and HAS-BEEN-USED slots of the given sndfile object
 to 0. These slots keep track of how many times a sound will be used and has
 been used, which is useful for purposes such as incrementing
 start-time. These slots are set internally and are not intended to be set by
 the user.

ARGUMENTS

 - A sndfile object.

RETURN VALUE

 Returns 0.

EXAMPLE

;; First set the values of the WILL-BE-USED and HAS-BEEN-USED slots, as these
;; are 0 when a new sndfile object is created using make-sndfile. Set the
;; values, print them; reset both using reset-usage, and print again to see
;; the change.
(let ((sf-1 (make-sndfile "/path/to/sndfile-1.aiff"))))
  (setf (will-be-used sf-1) 11)
  (setf (has-been-used sf-1) 13)
  (print (will-be-used sf-1))
  (print (has-been-used sf-1))
  (reset-usage sf-1)
  (print (will-be-used sf-1))
  (print (has-been-used sf-1)))

=>
11 
13 
0 
0

SYNOPSIS

(defmethod reset-usage ((sf sndfile))

sndfile/spectrum [ Methods ]

[ Top ] [ sndfile ] [ Methods ]

DATE

 18th April 2024

DESCRIPTION

 This is a simple convenience method to access the get-spectrum function
 defined in get-spectrum.lsp 

ARGUMENTS

 - the sndfile object

OPTIONAL ARGUMENTS

 keyword arguments:
 any keyword arguments that the get-spectrum function (get-spectrum.lsp) can
 handle. E.g. :start-analysis 0.1 (seconds) or :order-by 'freq or 'amp

RETURN VALUE

 two values: a list of the frequencies detected and a list of their
 amplitudes. The ordering of the lists depends on the :order-by keyword
 argment (see above).

SYNOPSIS

#+clm
(defmethod spectrum ((sf sndfile) &rest keyargs &key &allow-other-keys)

sndfile/stereo [ Methods ]

[ Top ] [ sndfile ] [ Methods ]

DESCRIPTION

 Test whether the CHANNELS slot of a given sndfile object is set to 2.

ARGUMENTS

 - A sndfile object.

RETURN VALUE

 Returns T if the CHANNELS slot is set to 2, otherwise returns NIL.

EXAMPLE

;; The method make-sndfile creates a sndfile object with the CHANNELS slot set
;; to NIL. Make a sndfile object, test to see whether the value of the CHANNELS
;; slot is 2; set the CHANNELS slot to 2 and test again.
(let ((sf-1 (make-sndfile "/path/to/sndfile-1.aiff")))
  (print (stereo sf-1))
  (setf (channels sf-1) 2)
  (print (stereo sf-1)))

=>
NIL 
T

SYNOPSIS

(defmethod stereo ((sf sndfile))