Opusmodus 4.0.30320 (Update)

The new Spectral Analysis Tool and Audio Engine functions are currently available only on macOS. The Windows version will be available shortly.

Spectral Analysis Tool

Overview

The Spectral Analysis window provides a real-time visualisation and control interface for frequency-domain analysis of audio signals. It combines Fast Fourier Transform (FFT) processing with a configurable analysis environment, supporting in-depth inspection of frequency components over time. The display includes magnitude spectra and peak detection, facilitating detailed timbral and structural audio analysis.

In addition to its analytical capabilities, the environment supports direct integration with compositional workflows. The Export Partials function enables the extraction and preservation of spectral data in a format compatible with the Opusmodus library system. This allows composers to employ spectral data as a generative resource, thereby placing the techniques of spectral composition, including orchestration, transformation, and algorithmic modelling, immediately at their disposal.

Spectrum View (Graph Area)

X-axis:			(Frequency, logarithmic scale): Ranges from ~8.17 Hz to 20 kHz					(depending on user input).
Y-axis:			(Normalised Amplitude): Ranges from 0.0 to 1.0.
Bars:			Represent the magnitude spectrum at the current frame.
Curve Line:		Shows averaged or smoothed spectral envelope.
Peak:			Display detected frequency peaks (e.g., 21, 69, 144 etc. in Hz).

Top Information Bar

Fps:			Frames per second of visual refresh.
RMS:			Root Mean Square amplitude of current frame.
Bars:			Number of spectral bins displayed.
Pos:			Current time/frame position and total duration.
Cen:			Spectral centroid (in Hz).
Roll:			Spectral roll-off frequency (in Hz).
Spr:			Spectral spread (standard deviation from centroid, in Hz).
Flat:			Spectral flatness (0.0 = harmonic; 1.0 = noise-like).

Control Buttons and Options

Play			Initiates playback and real-time analysis.
Rewind			Resets position to start of audio buffer.
Scale: Log		Selects frequency scale (e.g., Logarithmic or Linear).
Show Octaves	Displays octave grid overlays.
Analyser		Opens or configures the main Analyser module.

Analysis Parameters

FFT size		Number of points in FFT computation; affects
                frequency resolution, default: 16384.
Window size		Size of analysis window (samples); affects time resolution,
				default: 2048.
Hop size		Overlap between windows (samples), default: 1024.
Frame interval	Time interval (seconds) between frames, default: 0.01.
Min peak diff	Minimum difference between adjacent peaks for detection,
				default: 0.01.
Min amp (dB)	Minimum amplitude threshold for rendering spectrum,
				default: -90.
Under-peak (dB)	Threshold below peak for considering partials, default: -60.
Min freq (Hz)	Lower bound of frequency range displayed, default: 8.1758.
Max freq (Hz)	Upper bound of frequency range displayed, default: 12543.855.
Window			Type of windowing function used for FFT (e.g., Hanning,
				Hamming, Blackman). Can be selected live to immediately
                observe its effect on the spectral analysis, default: :hanning.

Inactive Buttons (Context-Sensitive)

Export Partials  (Disabled):

Enables the export of spectral partials once sufficient analysis data is available. Upon activation, this function saves the extracted partials in a file conforming to the Opusmodus library format. The file is stored in the designated library location and indexed automatically for future retrieval, reuse in composition, or further spectral processing.

Resanple Rect (Disabled):
Once active, performs rectangular resampling of the analysed audio. The resampled signal is saved as an audio file in the Media/Audio directory. The newly generated file is indexed automatically, allowing direct access through the Opusmodus Spectral Analysis or for subsequent processing.

Interactive Controls and Selection Tools

Timeline Selection (Shift + Click & Drag)

Holding the Shift key while clicking and dragging horizontally across the graph area allows the user to define a temporal selection on the timeline. This operation sets the active region for analysis playback and data export.

• The horizontal extent corresponds to the time range (start - end) under analysis.

• This selected interval can be used to constrain playback or to focus data extraction (e.g., exporting partials within the selected window).

Rectangular Selection (Option + Click & Drag)

Holding the Option (Alt) key while dragging the mouse enables a rectangular selection within the spectral display. This selection defines both frequency and time bounds.

• The vertical axis of the selection restricts frequency range.

• The horizontal axis restricts time range.

• This selection becomes active for specific functions such as resampling or focused spectral export.

Once defined, the rectangular region is visually highlighted and is used as a contextual domain for subsequent operations.

Graphical Labels

Peak Frequency:	Numeric labels (e.g., 21, 69, 144) appear above detected spectral
				peaks, denoting the frequency (in Hz) of dominant components.
Cursor Markers:	While hovering or selecting, real-time frequency and amplitude
				information may be displayed depending on implementation.
Time Cursor:	A vertical line or pointer indicates the current playback or analysis
				frame.

Keyboard Shortcuts

Spacebar		Play/Pause the analysis. Starts or halts real-time playback.
Return			Rewind to the beginning of the signal buffer.

Audio Engine

audio-play-file audio-file &key start end pos len amp fade-in fade-out

Arguments and Values:

audio-file		Pathname designator (string or pathname).
start			(optional) real ≥ 0. Start time in seconds.
end				(optional) real ≥ 0. End time in seconds (strictly ≥ start).
pos				(optional) real ≥ 0. Start time in seconds.
len				(optional) real ≥ 0. Duration in seconds.
amp				(optional) real in [0.0, 1.0]. Playback gain. Default: 1.0.
fade-in			(optional) real ≥ 0. Fade-in time in seconds. Default: 0.0.
fade-out		(optional) real ≥ 0. Fade-out time in seconds. Default: 0.0.

Description:

Plays a region of an audio file with optional gain and linear fades. The time window is specified by either (:pos p :len l) or (:start s :end e); mixed forms (:pos with :end, or :start with :len) are accepted. If the argument has no directory component, the function searches the project’s media/audio directory for a file of that name. This enables shorthand calls such as: "marangona" which looks for media/audio/marangona and plays it if found. If the file cannot be located there (and no absolute/relative path was given), an error is signalled.

Example:

Play the whole file:

(audio-play-file "marangona")

Play from 2.3 s for 2.0 s:

(audio-play-file "marangona" :start 2.3 :end 4.3)

Play from 2.3 s for 2.0 s, with a short fade-in and fade-out:

(audio-play-file "marangona" :pos 2.3 :len 2.0 :fade-in 0.5 :fade-out 0.5)

audio-mix &rest tracks

Arguments and Values:

tracks			Track plists. Two track kinds are recognised:

Audio track:

:start			Real ≥ 0. Track offset in seconds.
:segments     	List of audio segments (SEGMENT objects or plists).

Per-segment keys:

:pos/:len
 or
:start/:end		Required; window in seconds (mixed forms allowed).
:amp			(optional) real in [0, 1]. Segment-level gain (applied after track gain).
:fade-in		(optional) real ≥ 0. Fade-in time in seconds.
:fade-out		(optional) real ≥ 0. Fade-out time in seconds.
:silence		(optional) real ≥ 0. Seconds of silence inserted before the next segment.
:audio			String (single file) or list of files. If a list, files are used cyclically across segments.

(Note: :audio within a segment plist is ignored by the mixer; use the track’s :audio list to vary files across segments.)

Score track:

:start			Real ≥ 0. Track offset in seconds.
:segments		List of score segments (plists).

Per-segment keys:

:pos/:len
or
:start/:end		bars (integers; :len counts bars inclusively).
:tempo and :ts 	(optional) to compute wall-time when :at is omitted.
:silence		(optional) seconds, or a musical value together with :bpm.
:at 			(optional) seconds; schedules the segment at an absolute wall-time (disables cursor advance).
:score			Score designator (symbol, quoted symbol, or score object).
:ignore-ports	(optional) port filter passed to the sequencer.

Description:

Starts an audio/MIDI scene immediately. For each track, segments are scheduled on a serial cursor beginning at :start; the cursor advances by each segment’s duration plus any :silence (score segments may instead use absolute :at). Audio segments are rendered through a multichannel mixer; score segments are compiled as required and launched on the same wall-time base.

Example:

Score track with notated silence:

(audio-mix
'(:start 0.0
   :segments ((:start 1 :len 1)
              (:silence 3/4 :bpm 72)
              (:start 2 :len 1))
   :score (voice-variant1)))

Score track with per-segment tempo and metre:

(audio-mix
'(:start 0.0
   :segments ((:start 1 :end 1 :tempo 86 :ts 1/4)
              (:start 5 :end 5 :tempo 72 :ts 2/4))
   :score (voice-variant1 La-Marangona)))

Score segments pinned to absolute seconds:

(audio-mix
'(:start 0.0
   :segments ((:pos 1 :len 2 :tempo 90 :ts 4/4 :at 1.0)
              (:pos 5 :len 4 :tempo 90 :ts 4/4 :at 2.0)
              (:pos 9 :len 1 :tempo 120 :ts 3/4 :at 3.2))
   :score (La-Marangona voice-variant1)))

Mixed score + audio tracks:

(audio-mix
'(:start 1.0
   :segments ((:pos 3 :len 4) (:pos 2 :len 4))
   :score (La-Marangona voice-variant1))

'(:start 1.0
   :segments ((:start 0.0 :end 4.0 :amp 0.3
               :fade-in 1.0 :fade-out 1.0 :silence 1.0)
              (:start 0.0 :end 3.0 :amp 0.7 :fade-in 1.0 :fade-out 2.5))
   :audio ("dada" "marangona"))
)

AUDIO-MIX constructs graphs and opens resources at call time. With many tracks/segments this can introduce start-up jitter and inter-track skew. For timing-critical playback, compile first (audio-compile-scene 'cue …) and then play with

(audio-play-scene 'cue).

audio-compile-scene name &rest tracks

Arguments and Values:

name			Symbol naming the prepared scene.
tracks			Same track plists as accepted by audio-mix.

Description:

Prepares a scene for later playback. Audio tracks are stored as normalised arguments; MIDI tracks are preprocessed into runnable jobs (scores are validated/compiled). The prepared scene is placed in an internal registry under name. AUDIO-COMPILE-SCENE is designed for timing-critical playback. It prepares all audio/MIDI resources ahead of time so that AUDIO-PLAY-SCENE can start deterministically with minimal start-up latency.

Example:

(audio-compile-scene
'demo
'(:audio "vox.wav" :segments ((:pos 0 :len 2.0) (:pos 3 :len 1.0)))
'(:score 'my-score :segments ((:pos 1 :len 8))))

Play the scene:

(audio-play-scene 'demo)

Deterministic start with minimal launch latency:

(audio-compile-scene
'cue-A
'(:audio "drums1.wav" :segments ((:pos 0 :len 8) (:pos 8 :len 8)))
'(:audio "bass3.wav" :segments ((:pos 0 :len 16)))
'(:score 'click :segments ((:pos 1 :len 16))))

(audio-play-scene 'cue-A)

audio-play-scene name

Arguments and Values:

name			A previously compiled scene name (symbol or string).

Description:

Executes a scene prepared by AUDIO-COMPILE-SCENE. Playback starts deterministically, using the precomputed timelines, fades, and resource allocations for minimal launch latency and reliable synchronisation.

Example:

Minimal compile then play (single audio track):

Compiles a simple scene with one audio track containing two segments, then launches it. Precompilation removes set-up latency (file opening, mixer graph initialisation) from the start call.

(audio-compile-scene
'mixA
'(:audio "dada"
   :segments ((:pos 0.3 :len 2.0)
              (:pos 1.3 :len 2.0))))

(audio-play-scene 'mixA)

Three audio tracks with randomised segments; deterministic launch:

Builds three segment lists with AUDIO-MAKE-SEGMENTS (six segments each, drawn with RND-SAMPLE), schedules the tracks at different absolute offsets, compiles the scene, and plays it. Use a fixed RNG seed if you require reproducibility; otherwise the concrete values will vary per run.

(setf seg1 (audio-make-segments
            :start    (rnd-sample 6 '(0.0 3.0 6.0))
            :len      (rnd-sample 6 '(3.0 5.25 4.0))
            :amp      (rnd-sample 6 '(0.1 0.2 0.3))
            :fade-in  (rnd-sample 6 '(0.0 1.5 6.0))
            :fade-out (rnd-sample 6 '(2.5 0.5 6.0))))

(setf seg2 (audio-make-segments
            :start    (rnd-sample 6 '(0.0 3.0 6.0))
            :len      (rnd-sample 6 '(2.5 5.25 2.8))
            :amp      (rnd-sample 6 '(0.6 0.8 0.6))
            :fade-in  (rnd-sample 6 '(0.0 1.5 6.0))
            :fade-out (rnd-sample 6 '(2.5 0.5 6.0))))

(setf seg3 (audio-make-segments
            :start    (rnd-sample 6 '(0.0 3.0 6.0))
            :len      (rnd-sample 6 '(4.0 5.25 6.8))
            :amp      (rnd-sample 6 '(0.4 0.2 0.1))
            :fade-in  (rnd-sample 6 '(0.0 1.5 6.0))
            :fade-out (rnd-sample 6 '(2.5 0.5 6.0))))

(audio-compile-scene
'scene1
'(:start 0.0 :segments seg1 :audio "cello")
'(:start 2.0 :segments seg2 :audio "cello")
'(:start 3.0 :segments seg3 :audio "cello"))

(audio-play-scene 'cello1)

resample-to-rect source &key rect out sr bits normalize taps window bp taper-ms remove-dc dither debug

Arguments and Values:

source			Audio file source. Pathname designator (string or pathname). If no directory
				component is supplied, the short name is resolved in media/audio.

rect 			(optional) time–frequency selection. Supported fields (any subset):

				:time-start/:time-end
				(aliases :t0/:t1 - :u0/:u1), fractions of file length in [0,1].

				:start-sec/:end-sec
				(aliases :t0s/:t1s) - seconds.

				:i0/:i1
				sample indices (half-open: :i0 inclusive, :i1 exclusive).

				:freq-low-hz/:freq-high-hz
				(aliases :hz0/:hz1) - Hz.

				:freq-low/:freq-high
				(aliases :v0/:v1 - :f0/:f1) - Hz.

out 			(optional) base name or path (without extension) for the output file.
				Default: "rs-<source-name>-slice" in the project’s audio output
				location. Name collisions are resolved automatically.

sr				(optional) output sample rate in Hz. Default: 48000.

bits			(optional) output bit depth (e.g., 16, 24, 32). Default: 24.

normalize		(optional) boolean. If true, peak-normalises after DC removal and before
				taper/dither. Default: T.

taps			(optional) FIR length for the band-pass: odd integer or :auto. Default: 1025.
				Even values are promoted to the next odd.

window			(optional) FIR window (e.g., :hanning, :blackman). Default: :hanning.

bp				(optional) boolean. If true, apply a linear-phase band-pass defined by
				the resolved f0/f1 when meaningful. Default: T.

taper-ms		(optional) half-cosine edge taper per end (milliseconds). Default: 5.

remove-dc		(optional) boolean. If true, subtracts the mean per channel before
				normalisation. Default: T.

dither			(optional) boolean. If true and bits = 16, applies TPDF dither
				before quantisation. Default: T.

debug			(optional) boolean. If true, prints processing statistics to the console.
				Default: NIL.

Description:

RESAMPLE-TO-RECT extracts a rectangular selection in time and frequency from source, optionally applies a symmetric linear-phase band-pass, resamples to sr, post-processes to avoid clicks, and writes the result as a WAV file.

Selection semantics.

rect may express time in fractions, seconds, or sample indices and frequency in Hz. Time bounds are mapped to frame indices using the source rate; frequency bounds are clipped to [0, Nyquist] with Nyquist = src-sr/2. Indices are half-open (:i0 inclusive; :i1 exclusive).

Filtering.

If bp is true and 0 ≤ f0 < f1 ≤ Nyquist, a linear-phase FIR (taps, window) is designed and applied at the source rate. :auto chooses an appropriate length; even taps are promoted to the next odd. If bp is NIL or the band spans the full range, filtering is skipped.

Resampling and formatting.

After any filtering, the signal is band-limited resampled to sr (or left at the source rate if equal). Quantisation uses bits, with optional TPDF dither when bits = 16. The output container is always WAV/PCM.

Anti-click chain.

Processing order is: DC removal (:remove-dc) → normalise (:normalize) → half-cosine taper (:taper-ms) → optional dither (:dither).

Example:

Audio file data:

(audio-metadata "marangona")
=> (:format "WAVE" :ctype "PCM_16"
    :channels 2 :frames 1079210
    :src-sr 44100.0D0 :src-bits 16
    :out-sr 44100.0D0 :out-bits 16
    :i0 0 :i1 1079210
    :start-sec 0.0D0 :end-sec 24.4718820861678D0
    :f0 0.0D0 :f1 22047.794634103775D0
    :apply-bp t
    :taps 1025
    :window :hanning)

The expression below extracts the time segment from sample index 23445 (inclusive) to 48383 (exclusive) of the audio source "marangona" and applies a linear-phase band-pass retaining only the frequency range 40–500 Hz.

(resample-to-rect
 "marangona"
 :rect '(:i0 23445 :i1 48383 :hz0 40 :hz1 500))

The result is rendered with the default output sampling parameters (sample rate and bit depth inherited from the source unless :sr or :bits are supplied) and with the original channel count preserved.

The resulting audio file is written automatically to Media/Audio/ using the project’s naming scheme and the container/encoding of the source unless overridden.

More examples:

(resample-to-rect "marangona"
                  :rect '(:u0 0.12 :u1 0.35 :v0 0.045 :v1 0.136)
                  :taps 1025 :out "rs-ma-mid" :sr 48000 :bits 24
                  :normalize t :debug t)

(resample-to-rect "marangona"
                  :rect '(:u0 0.12 :u1 0.35 :v0 0.0127 :v1 0.0136)
                  :bp t :taps 1325 :taper-ms 70 :out "rs-ma-low"
                  :sr 48000 :bits 24 :normalize nil :window :riemann)

audio-metadata source &key rect sr bits taps window bp

Arguments and Values:

source			Audio file source. Pathname designator (string or pathname).
rect			A time–frequency rectangle understood by your spectral toolkit. If NIL, the full time
				span and [0, Nyquist] frequency span are assumed.
sr 				Optional output sample rate (Hz). Defaults to the source rate.
bits			Optional output bit depth (e.g., 16, 24, 32). Defaults to the source bit depth.
taps			FIR length (odd integer) or :auto. Default 1025. Even values are promoted
				to the next odd.
window 			FIR window specifier (e.g., :hanning, :blackman).
bp				Boolean. If true, apply band-pass defined by f0/f1 (derived from rect)
				when meaningful. Default T.

Description:

AUDIO-METADATA computes - without performing any heavy resampling - the concrete parameters that would be applied by RESAMPLE-TO-RECT for the given source and rect. It returns (a) container/codec information; (b) resolved input/output sampling parameters; (c) the time selection both in frames (:i0/:i1) and seconds; (d) the frequency selection (:f0/:f1); and (e) FIR design settings (length/window) and whether a band-pass should be applied. Time bounds are mapped to frame indices using :src-sr and clipped to [0, :frames]. Frequency bounds are clipped to [0, Nyquist] with Nyquist = :src-sr/2. Even :taps are promoted to the next odd to ensure a symmetric linear-phase design. If bp is NIL, :apply-bp is NIL regardless of rect.

Example:

Full-file data. Looks up Media/Audio/marangona if no path component is supplied:

(audio-metadata "marangona")
=> (:format "WAVE" :ctype "PCM_16"
    :channels 2 :frames 1079210
    :src-sr 44100.0D0 :src-bits 16
    :out-sr 44100.0D0 :out-bits 16
    :i0 0 :i1 1079210
    :start-sec 0.0D0 :end-sec 24.4718820861678D0
    :f0 0.0D0 :f1 22047.794634103775D0
    :apply-bp t
    :taps 1025
    :window :hanning)

Best wishes,

Janusz