;*********************************************************************
; OM-SoX, (c) 2011-2013 Marlon Schumacher (CIRMMT/McGill University) *
;             http://sourceforge.net/projects/omsox/                 *
;                                                                    *
;  Multichannel Audio Manipulation and Functional Batch Processing.  *
;        DSP based on SoX - (c) C.Bagwell and Contributors           *
;                  http://sox.sourceforge.net/                       *
;*********************************************************************
;
;This program is free software; you can redistribute it and/or
;modify it under the terms of the GNU General Public License
;as published by the Free Software Foundation; either version 2
;of the License, or (at your option) any later version.
;
;See file LICENSE for further informations on licensing terms.
;
;This program is distributed in the hope that it will be useful,
;but WITHOUT ANY WARRANTY; without even the implied warranty of
;MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;GNU General Public License for more details.
;
;You should have received a copy of the GNU General Public License
;along with this program; if not, write to the Free Software
;Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,10 USA.
;
;Authors: M. Schumacher

(in-package :om)

; %%%%%%%%%%% SOX ANALYSIS FUNCTIONS %%%%%%%%%%%

; should probably add methods for samplerate, channels, filetype, and comment

(defmethod! sox-channels (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Number of channels in the audio."

  (let ((thestring "channels"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-samplecount (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Number of samples in the audio. Equivalent to samplerate * duration (sec)."

  (let ((thestring "samples"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))

(defmethod! sox-samples (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Number of samples in the audio. Equivalent to samplerate * duration (sec)."

  (let ((thestring "sample-analysis"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))

(defmethod! sox-duration (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Duration of audio (in seconds)."

  (let ((thestring "duration"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-scale-factor (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "The factor which would make the audio as loud as possible without clipping."

  (let ((thestring "scale-factor"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))

; AMPLITUDES

(defmethod! sox-peak-amplitude (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc " The peak (absolute) amplitude value in the audio"

  (let ((thestring "peak amplitude"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))

(defmethod! sox-max-positive-amplitude (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc " The maximum sample value in the audio; usually this will be a positive number"

  (let ((thestring "max positive amplitude"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-max-negative-amplitude (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc " The minimum sample value in the audio; usually this will be a negative number"

  (let ((thestring "max negative amplitude"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))                                                     


(defmethod! sox-mean-amplitude (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "The average of each sample in the audio. A non-zero value indicates the presence of a D.C. offset"

  (let ((thestring "mean amplitude"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-rms-amplitude (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "The RMS amplitude of the audio, i.e. the level of a D.C. signal that would have the same power as the audio's average power."

  (let ((thestring "rms amplitude"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-max-delta-amplitude (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "The maximum (amplitude) difference between two consecutive samples in the audio."

  (let ((thestring "max delta amplitude"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-min-delta-amplitude (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "The minimum (amplitude) difference between two consecutive samples in the audio."

  (let ((thestring "min delta amplitude"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-mean-delta-amplitude (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "The average (amplitude) difference between consecutive samples in the audio."

  (let ((thestring "mean delta amplitude"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-rms-delta-amplitude (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "The average difference between consecutive rms-values (default rms window size: 50ms) in the audio."

  (let ((thestring "rms delta amplitude"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-f0 (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Rough (time-domain) estimate of fundamental frequency. In Hz."

  (let ((thestring "fundamental frequency"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-headroom (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Indicates the headroom (in dBFS), i.e. the value for amplfication which would make the audio as loud as possible without clipping."

  (let ((thestring "headroom"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-dc-offset (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "DC offset in the audio (in the range +/- 1."

  (let ((thestring "dc offset"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-peak-level (&key sox-append)
            :icon 80
            :initvals '(nil)
            :indoc (list *sox-append-doc*)
            :doc "Peak level is the peak value (in dBFS) in the audio." 

            (let ((thestring "peak level"))
              (when sox-append
                (setf thestring (x-append thestring sox-append)))
              thestring))


(defmethod! sox-rms-level (&key sox-append)
            :icon 80
            :initvals '(nil)
            :indoc (list *sox-append-doc*)
            :doc "RMS level of the audio (in dBFS). Default size of RMS window is 50ms."

  (let ((thestring "rms level db"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-rms-peak-level (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "The peak value (in dBFS) for RMS level measured over a short window (default 50ms)."

  (let ((thestring "rms peak level"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-rms-trough-level (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "RMS Trough is the trough value (in dBFS) for RMS level measured over a short window (default 50ms)."

  (let ((thestring "rms trough level"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-crest-factor (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Crest factor is the standard ratio of peak to RMS level." 

  (let ((thestring "crest factor"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-flat-factor (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Flat factor is a measure of the flatness (i.e. consecutive samples with the same value) of the signal at its peak levels (i.e. either Min level, or Max level)."

  (let ((thestring "flat factor"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-peak-count (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Peak count is the number of occasions (not the number of samples) that the signal attained either Min level, or Max level."

  (let ((thestring "peak count"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-bit-depth-ratio (&key sox-append)
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Indicates the ratio of used bits vs unused bits in the audio."

  (let ((thestring "bit depth ratio"))
    (when sox-append
      (setf thestring (x-append thestring sox-append)))
    thestring))


(defmethod! sox-dft ()
  :icon 80
  :initvals '(nil)
  :indoc (list *sox-append-doc*)
  :doc "Computes the input's power spectrum (rectangular-windowed 4096-point DFTs). Sox-analysis will return lists (i.e. spectral frames) containing lists of frequency/magnitude pairs"

  (let ((thestring
         "dft-analysis"))
    thestring
  ))