Acoustic Morphology Composer

What this does

Acoustic Morphology Composer makes a virtual acoustic space into a compositional filter. Draw walls, obstacles and apertures; place a sound source and up to four virtual microphones; then compute how a pressure wave propagates through that geometry. Each microphone receives a simulated impulse response (IR), which is used to filter an existing recording by convolution. The resulting spectral peaks, notches, delays and resonances depend on the space that was drawn.

Key Features:

• Interactive geometry editor: walls, rectangular obstacles and openings, with selectable objects, snapping, numeric properties and undo/redo.
• Two-dimensional FDTD wave simulation: pressure and particle-velocity propagation with reflections, diffraction and interference.
• Up to four virtual microphones: distinct geometry-derived IRs, individual outputs, mono mix or panned stereo mix.
• Acoustic Fingerprint: IR waveform, frequency response, energy decay, phase or spectrogram, resonant peaks and notches.
• Eight editable geometrical presets: from an open field to coupled chambers and a changing aperture.
• Acoustic States and Morph Timeline: store, compare, sequence and interpolate acoustic transformations.
• Sound-first workflow: offline audition, dry/wet balance, rendered Sound and optional IR/layer exports to Praat.
• Reproducible projects: saved geometry, states, timeline, processing settings and computed-response cache.

Quick start

1. In Praat, select exactly one Sound (mono or stereo) and run Acoustic_Morphology_Composer.praat from the AudioTools - py menu.
2. In the Python window, start with Presets → Resonant Chamber or Narrow Passage, or draw your own geometry.
3. Choose Draft while exploring, then press Compute. Wait for the response calculation to finish; geometry editing itself remains interactive.
4. Open Acoustic fingerprint to inspect the response, and Source & audition to play the original or processed recording and compare them using Matched level.
5. Move the microphone, adjust a wall or an opening, and press Compute again. Compare the resulting timbre and frequency response.
6. Use Store state to create a named copy of the current configuration. The editor stays on the original state: explicitly select the stored copy in States before editing it. Place the states on the Timeline for an evolving treatment.
7. In Render, choose the main output, wet/dry balance, tail policy and optional impulse-response or microphone-layer exports.
8. Press Render, then Return to Praat. Newly generated Sound objects appear in the Praat Objects window; the original recording is preserved.

Core concept

For a stationary acoustic state, the rendered signal is obtained by convolving the recording x(t) with the microphone response h(t): y(t) = x(t) * h(t). Different geometries or listening positions produce different impulse responses. The composer can use them as timbral structures, not merely as room reverberation effects.

Wavefield images, IRs and frequency-response plots are derived from the same acoustic simulation. The Wavefield display is an inspection tool; the finished audio, however, comes from the computed impulse response.

Geometry editor

The left side of the application contains a scaled room plan, with coordinates measured in metres. A single source is indicated by S; microphones are labelled individually. The geometry is converted into a numerical grid when a response is computed.

View aids: snap and its selectable grid step, grid, sim. cells (an overlay of the actual solid grid cells), Fit, Delete, Clear, Load geom. and Save geom. The Properties panel permits precise numerical editing of selected elements, the room dimensions and boundary conditions, or each microphone's name, gain, enabled state and stereo pan.

Interface and controls

Main toolbar

Window areas

Eight editable acoustic presets

The presets contain actual room geometries, source locations, microphones and boundary settings. They are starting points for composition, not fixed EQ curves; results vary when you change the geometry, source, microphone or solver settings.

Five compositional workflows

Acoustic states and response caching

A state stores the current geometry, sound-source position, microphones, boundary, simulation settings, state-specific rendering settings, name and notes. Use Store as new, Duplicate, New listener state, Rename, Delete, Recompute, Compute all outdated and Compare from the States tab.

Matching configurations can reuse cached responses. Changing only a microphone's name, gain, pan or enabled state does not require a new simulation. Moving, adding or removing a microphone does require a new simulation; so do changes to the source, geometry or acoustic calculation settings. Unaffected states retain their valid cached responses.

Timeline and acoustic morphing

Place a state at the Timeline cursor using Add keyframe. Each keyframe specifies the state to reach, its time, the preceding transition duration, the transition curve and an amount. At 100%, the new target state takes over; at 40%, it contributes 40% while the previous mixture retains 60%.

Drag a keyframe or transition edge to edit timing, double-click a keyframe for detailed values, or right-click it for state, curve and deletion options. Use Preview composition to hear the full trajectory before exporting.

Acoustic analysis and visualisation

The Measurements tab also reports source-to-microphone distance, first-arrival time, in-band level, spectral centroid, resonances, notches and energy distribution. Compare states overlays the responses of all checked, computed states; its difference curve compares the first two checked states to reveal changes in spectral shape and transmission level.

Physical level keeps a common reference (the modeled free-field response at 1 m); Normalized timbre compares shapes on normalized scales. Use physical level to study transmission loss; use normalized timbre when judging color independently of loudness.

Rendering and sound controls

Current-state controls

Project output controls

Multiple microphone wet layers are normalized by approximately 1 / sqrt(N) in combined mixes, where N is the number of contributing microphones. The stereo mix uses each microphone's gain and pan; a mono source is equal-power centered in stereo.

Mouse gestures and keyboard shortcuts

These commands apply when the relevant Python editor has keyboard focus; they are not Praat Demo-window shortcuts.

Outputs and project files

The Praat launcher exports the selected Sound to a temporary working session and imports only files explicitly returned by the Python application. The original source object remains unchanged. If the window is closed without Return to Praat, no new Sounds are imported.

Praat output names receive a collision-safe suffix if needed. The project does not embed or duplicate the original recording; it keeps a reference. A project can still preserve its acoustic design when the original source is absent. When running from Praat, the Sound currently supplied to the session remains the audio input; in standalone mode the user may load or relink a source. If the audio sample rate changes, the relevant IRs may need to be recomputed.

Praat Info report: following an export, Praat lists the imported objects, reports whether the main output preserves the original duration to within one sample (or includes a requested reverberation tail), and confirms that the original Sound object was not modified.

Requirements and installation

Place the two files side by side in the plugin's py directory:

plugin_AudioTools/
  py/
    Acoustic_Morphology_Composer.praat
    acoustic_morphology_composer.py

Install Python dependencies into the environment that Praat uses:

python -m pip install PySide6 numpy scipy soundfile pyqtgraph sounddevice

The launcher searches the Python environment specified by pyCandidate1$ near the top of the Praat script, then common Python commands on the system. It checks for required modules and explains if no suitable interpreter is found. On a machine with a dedicated Python environment, update pyCandidate1$ to point to the correct interpreter.

You can also launch the application independently with python acoustic_morphology_composer.py and use its Load source… and Export WAVs… commands.

Temporary sessions: the Praat launcher creates a private working folder under the system temporary directory (on Windows, normally %TEMP%). Temporary input, manifest and output files are cleaned up when the session ends. The launcher's Keep_session_files option retains them for troubleshooting; leave it off for normal use.

Command-line tools

The Python application also provides offline tests, example creation, model validation and manual access. Run these commands from the folder containing acoustic_morphology_composer.py:

python acoustic_morphology_composer.py --project FILE
python acoustic_morphology_composer.py --selftest
python acoustic_morphology_composer.py --selftest --praat "C:/path/to/Praat.exe"
python acoustic_morphology_composer.py --make-example DIR
python acoustic_morphology_composer.py --validate DIR
python acoustic_morphology_composer.py --manual

--project opens a saved project; --selftest runs the bundled checks, with --praat additionally enabling the Praat round-trip check; --make-example creates demonstration material; --validate performs musical and acoustic-model checks; and --manual prints the built-in manual. These tools are optional for normal composition.

How the acoustic method works

The engine solves the linear acoustic equations on a two-dimensional staggered grid, keeping acoustic pressure at cell centers and particle velocity at cell faces. The numerical time step respects the Courant stability limit for two dimensions.

Rigid walls reflect, partially absorbing boundaries use an approximate frequency-independent impedance, and absorbing outer boundaries use a numerical absorbing layer. Apertures allow diffraction and interference to emerge from the computed field. Source and receiver locations are interpolated on the grid.

Simulation quality

The application calculates and reports its actual reliable bandwidth for the selected grid, speed of sound and sampling rate; the numbers above are reference values, not universal limits. Finer grids cost substantially more computation and memory.

The optional 2.5-D correction reduces the characteristic spectral tilt and time-domain wake of a two-dimensional line-source response, making its direct arrival more point-source-like. It does not transform the entire simulation into a physically accurate three-dimensional room model.

Limitations and interpretation

• 2-D rather than 3-D: the virtual space has no floor, ceiling or height modes; decay times and spatial spreading are those of a two-dimensional model.
• Instrument radiation: a cello, flute or voice is represented as an omnidirectional excitation point, not as a measured directional radiation pattern. The input recording is processed through the simulated space.
• Limited frequency band: frequencies above the solver's reliable band are either preserved dry, attenuated or processed by a labelled creative extension, not accurately propagated by FDTD.
• Approximate materials: absorption is frequency-independent; it is not a complete model of real acoustic materials.
• Geometry sampling: very narrow openings and diagonal walls are quantized by the grid; use the sim. cells overlay and adjust quality where needed.
• Finite response length: long decays can reach the end of the simulated IR. The application warns and fades the truncated end; extend the response duration or increase absorption.
• Static-state morphing: ordinary timeline crossfades do not numerically simulate continuously moving walls. Intermediate-geometry morphing generates several independently computed states.
• Offline workflow: Compute and Render are separate from mouse interaction. The application is intended for composition, not live acoustic feedback.
• Playback requirements: direct listening inside the Python window depends on a functioning audio device and optional playback library; exports do not.

Musical applications

A bowed cello tone as spectral architecture

Load a sustained cello tone, use Resonant Chamber and compute. Compare its response with Open Field, listening at matched level. Inspect which harmonics the geometry emphasizes or suppresses, then alter the chamber dimensions and repeat. The frequency response—not an arbitrary fixed filter curve—explains the timbral changes.

Compose an evolving resonant space

Use Moving Aperture as a starting point. Place its acoustic states on the Timeline and vary transition timing. Choose Input crossfade if you want earlier resonances to continue decaying as new ones enter. Try Geometry morph… when you want a sequence of physically recomputed aperture widths.

Make counterpoint from one sound

Use Dual Chamber with two microphones at different listening positions. Export their separate processed layers, then arrange and mix those layers in a larger composition. Their distinct timbres share a common source and simulated geometry.

Moving listener as timbral gesture

Store one state, use New listener state, and move a microphone while preserving the walls and source. Compute the new IR, place both states on the Timeline and use the transition as a composed change of perspective.

Build a library of acoustic instruments

Save a project of carefully designed resonant chambers, passages and cavities. Reopen the acoustic design and apply it to different source recordings. This separates the compositional structure of the filter from any one input sound.