Praat AudioTools Live Lab

What this does

Praat AudioTools Live Lab turns a physical microphone or instrument input into a performance-controlled analysis–resynthesis instrument. Hold a momentary MIDI pedal or the keyboard capture key to record an acoustic gesture; release it to send the completed take through one of nine existing Praat AudioTools Live chains. The resulting sound enters a temporary Result Bank and can be played as a one-shot event or introduced through a controlled crossfade.

The system separates live capture, Praat rendering and playback. You can make another recording while an earlier take is being processed or played, and a slow rendering job does not block the audio callback. Unlike automatic phrase-detection systems, the musician defines the capture boundaries by holding and releasing a pedal.

Key capabilities in v1.1.1:

• Hold-to-record performance: MIDI Note or CC pedal, MIDI Learn, selectable polarity, and a keyboard fallback.
• One shared physical audio input: selectable Mono or Stereo capture, configurable channels, direct-monitoring workflow.
• Nine existing Live chains: six fixed chains and three parameter-randomised versions; the originals remain unchanged.
• Isolated Praat worker: one processing job at a time, with a FIFO queue, runtime-derived adapters and a separate Praat process.
• Hybrid result handling: independent MANUAL or AUTO policy for each chain, Auto Suspend and Latest Capture Priority.
• One-shot playback: retrigger, manual crossfade, configurable 3-second default crossfade and Stop All.
• Explicit output routing: Stereo or Octophonic profiles, Front Stereo Pair for stereo results in eight-speaker layouts, and optional defined eight-to-two downmix.
• Temporary Result Bank: at least 16 entries, PIN protection, regeneration from original captures and explicit export.
• Output protection: adjustable lookahead peak limiter, meters and callback-overload diagnostics.
• Zero-residue design: dedicated session workspace, process guards, cleanup on normal shutdown and stale-session recovery after interruption.

Quick start

1. Place Live_Lab.praat and live_lab.py in the AudioTools installation as described in Installation and requirements. Keep the nine original Live chains in Vector Chain/.
2. Connect your microphone, instrument or external mixer to the physical audio interface. Configure input gain on the interface; use its direct monitoring rather than software-through monitoring in Live Lab.
3. Run Live_Lab.praat from Praat. No Sound needs to be selected first. In Praat 7, allow the required trust permission if prompted.
4. Open SETUP → Audio. Choose Host API (preferably ASIO on Windows), input and output devices, sample rate, block size, Mono or Stereo input, and the physical input-channel number(s). Click Apply & restart audio.
5. Open SETUP → Routing. Select Stereo or Octophonic, confirm the actual physical outputs, and use Test (-30 dBFS) or Test all in turn at a safe monitoring level.
6. Open SETUP → Praat. Verify the executable is detected and click Run worker self-test. The test result should become READY in the Result Bank; it tests the real worker path, not an arbitrary Live chain.
7. Open SETUP → MIDI, select the correct MIDI input port, choose Learn (press & HOLD) for Hold to Record, press and hold the pedal, and verify DOWN/UP feedback. If no pedal is available, use the keyboard F key.
8. In SETUP → Chains, choose MANUAL or AUTO for each chain. All nine start as MANUAL in a new configuration; crossfade defaults to 3.0 seconds if AUTO is enabled.
9. Return to PERFORMANCE, check that AUDIO is OK and capture is ARMED, choose a chain with 1–9, then hold the pedal/F to record and release it to submit.
10. When the result is READY, select it and use Space to play, or C to crossfade. Use Esc for Stop All. Close the Live Lab window when finished and check Praat's Info window for the shutdown report.

Core concept and signal flow

Python owns the full-duplex audio stream and the performance interface. A capture writer serialises finished takes outside the audio callback. A processing manager runs one headless Praat process per job; its worker loads the take, runs the selected original composition through an adapter, validates the output and returns a complete WAV for playback.

The Praat launcher remains open and occupied while the Python window is running, but the worker does not use the user's interactive Praat Objects list. The nine original chains are not overwritten or modified.

Nine Live processing chains

The numbered buttons correspond to six existing compositions and three parameter-randomised variants. The table below describes the stage order present in the supplied Live scripts; it does not imply that every stage produces a predetermined result for every recording.

At startup, SETUP → Chains → Re-check chain files performs a structural compatibility check. The runtime builds the processing adapter from the installed chain: it replaces the built-in microphone recording with the captured WAV, retains the chain's preparation and transformations, and removes its final internal Play command. A preflight check also inspects child-script argument counts and visible Draw/Play switches.

Hold-to-record capture and pre-roll

Pedal DOWN begins a capture and freezes the selected chain, its MANUAL/AUTO policy, crossfade time and job decision number. Pedal UP ends it, sends the audio buffer to the writer and moves the take into finalisation. The capture becomes a processing job only after its WAV is completely written.

Pre-roll is copied from the input ring into a preallocated capture buffer. The audio callback does not write WAV files to disk. A dedicated writer thread validates the captured samples and saves them within the private session workspace. FINALIZING prevents audio-device restart while a just-released take is still being written.

Live Lab does not route the incoming microphone signal back to the output stream. For onstage listening, use the interface's direct monitoring, an external monitor mixer or a suitable isolated signal path. Avoid allowing speaker playback to feed unintentionally into a microphone capture.

MIDI pedal, controller mapping and disconnection

In SETUP → MIDI, select an input port and optional MIDI channel (Omni or 1–16). Every performance action can be assigned via MIDI Learn to a suitable Note or CC message. The foot-pedal mapping uses Learn (press & HOLD).

Repeated Note On messages and CC fluctuations are handled as edges rather than repeated start commands. The Setup display shows pedal state, last incoming MIDI event and whether an event was filtered or unmapped. MIDI is optional: keyboard-only capture is supported when python-rtmidi is not installed.

Keyboard shortcuts and performance actions

These are the default key assignments, visible and editable under SETUP → Keyboard. Keyboard controls are suppressed while typing into setup text fields, and a focus-loss safeguard releases a keyboard-held recording key.

One-shot playback, layering and crossfades

Every processed result is a One-Shot. There is no looping in v1.1.1. A result ends naturally after its stored samples have played. It can be replayed on demand without invoking Praat again.

The default crossfade is 3.0 seconds per chain, adjustable under SETUP → Chains. The actual fade is capped at approximately half the incoming result's duration, so a very short clip does not spend its entire length fading in. Crossfade envelopes are equal-power for different results; transitioning a result into itself uses a constant-amplitude curve to avoid a correlated-signal boost.

The output engine applies a brief anti-click fade at the beginning and natural end of each voice. Result routing occurs before the shared output mix and limiter, so Mono, Stereo and eight-channel sounds can be combined in a single selected physical output space.

Auto Play, Manual Play and Latest Capture Priority

Each of the nine chains has an independent policy, configured in SETUP → Chains. A new installation starts with every chain in MANUAL. In MANUAL, the completed result remains READY. In AUTO, the result can enter through Crossfade only when it still represents the performer's latest relevant decision.

The decision counter advances when you begin a new capture, Regenerate, manually Play/Retrigger, manually Crossfade or issue Stop All. For example, if Take T008 is still processing when you start T009, T008 will not interrupt the newer performance decision when it finally completes. Instead, it becomes READY for manual use.

Auto Suspend is a separate global control. Turning it ON does not cancel processing or delete audio; it makes newly finished AUTO results wait in the bank. It can be toggled from the Playback panel or with A.

Result Bank, PIN and regeneration

The Result Bank stores completed and pending processing results together with references to their original captured takes. The default capacity is 16 results and the default memory budget for processed audio is 1,500 MB; both are configurable under SETUP → Capture.

Eviction avoids PINNED, QUEUED, PROCESSING, currently PLAYING and not-yet-started scheduled voices. When the Bank is full and every entry is protected, new captures are refused rather than silently deleting protected material. When the final result referencing a take is evicted, its temporary original WAV may also be released.

Output routing: Stereo and Octophonic

Routing is explicit: no hidden channel wraparound and no unapproved eight-to-stereo fold-down. Live Lab supports output profiles named Stereo and Octophonic; physical channel numbering is one-based in the settings.

Available Mono gain laws are −3 dB equal-power (default), −6 dB linear and 0 dB dual mono. Octophonic mono placement can use Front Stereo Pair, one speaker or an eight-speaker distribution. Defined eight-to-two presets are a ring/azimuth equal-power map and an odd/even grouping, both labelled −6 dB in the interface; None (reject) is the default.

In SETUP → Routing, specify output profile, stream channel count, physical L/R channels, speaker 1–8 mapping, Front Stereo Pair, mono mapping, downmix preset, ring starting azimuth and per-channel trim. Validate & apply checks the configuration. Test (-30 dBFS) sends a short 1 kHz test tone to an individual physical output; Test all in turn steps through every open output.

Dynamics, output metering and limiter

After routing and mixing, the output is scaled by per-channel trims and the Master gain. The default output protection is ON, with a ceiling of −0.3 dBFS. The v1.1.1 engine uses a 2 ms lookahead peak limiter with a 1 ms attack and approximately 250 ms release; the code retains a numerical safety clamp as a backstop rather than its normal limiting mechanism.

SETUP → Routing provides a limiter enable control and an adjustable ceiling. The PERFORMANCE view shows input/output meters plus status for limiter activity and audio callback overloads. The master slider ranges from −40 to +6 dB. Raising gain or using aggressive speaker trims increases the load on output protection.

Performance View: main display

Live Lab opens in PERFORMANCE view. The dark application window is designed for a stage-readable overview, while this documentation page uses the light, print-friendly Praat AudioTools reference style.

PRAAT AUDIOTOOLS  ·  LIVE LAB 1.1.1
AUDIO: OK    MIDI: connected    ARMED

GLOBAL INPUT       Stereo · IN 1+2
PROCESSING CHAINS  [1] Live 1 MANUAL  [8] Live 2 Random AUTO · xf 3.0s
CAPTURE            HOLD TO RECORD | next take T009
PROCESSING         T008.1 · Live 2 Random · 6 s | queued 1
PLAYBACK           NOW PLAYING T007.1 | ONE-SHOT
                   NEXT / READY T006.1 · Live 4 · READY
RESULT BANK        T006.1 READY | T007.1 PLAYING | T008.1 PROCESSING
OUTPUT             Octophonic · Front Stereo Pair 1/2

READY means a result can be triggered; PROCESSING is not a playback instruction. You may continue to perform acoustically while either state is shown. During keyboard-controlled capture, keep the application window focused.

Setup View: nine tabs

SETUP groups detailed options into nine tabs. Most device and routing settings are normally prepared during sound-check rather than changed mid-performance.

Performance presets and persistent configuration

Open SETUP → Presets to Save, Load or Delete a named setup. Presets store routing, chain MANUAL/AUTO policies and crossfade durations, Master gain, capture settings, keyboard maps and MIDI mappings/thresholds. Audio device choices are intentionally not part of a performance preset: a setup can be moved to another venue and then associated with its local hardware.

The application also maintains a general configuration file, plugin_AudioTools/live_lab_config.json. This persistent file is distinct from the temporary audio session and is not deleted when the application closes.

Praat rendering, compatibility and self-test

Live Lab does not ask the nine source scripts to record another microphone input. For each job it generates a temporary adapter from the installed original chain. It reads the captured WAV, converts the processing input to Mono/44.1 kHz as needed, executes the original chain stages without the chain's final Play command, and saves a validated 24-bit WAV result.

The manager launches a separate headless Praat process and runs one job at a time (FIFO). Each job has its own temporary folder containing an adapter, worker status, captured handoff/result and diagnostic text while needed. The result is loaded into Python only after Praat exits and the audio file passes sample rate/channel/frame validation.

In SETUP → Praat, leave the executable field empty for automatic detection, or browse to the correct executable. The default worker timeout is 300 seconds. Run worker self-test makes a short synthetic audio example and verifies the worker's file handoff, rendering, resampling and return path. It does not exercise all nine transformation chains.

The source code contains a report of headless runtime testing of all nine chains on Linux with Praat 6.4.63 and 7.0. Treat this as a development test report; repeat the actual chain and audio-driver tests on the performance computer before relying on the system in a concert.

Randomised chains and repeatability

The Result Bank stores a numeric random seed with each processing job. In the source implementation, Live 4, 5 and 6 are marked reproducible because their processing chains can follow the worker's seed; repeated runs on the same Praat build are reported to match at sample level. Live 1–3 and the three Random variants include internally re-randomising stages and are not promised to reproduce identically from the recorded seed.

Regenerate intentionally creates a new processing job with a new seed. The stored seed is useful metadata, but does not make every script or every version of Praat deterministically equivalent.

Exporting recordings and results

Select an entry in the Result Bank and click Export selected. Live Lab writes available audio and a metadata record into the configured export folder, which defaults to Documents/Live Lab Exports/ (or a corresponding home-directory location if Documents is unavailable).

An export may contain only the WAV files currently available, but still writes a metadata JSON file. Export is the deliberate preservation mechanism. Ordinary capture WAVs, adapters and processing outputs within the session folder are disposable and are not intended to become a permanent library automatically.

Temporary files, process safety and session cleanup

Temporary file management is a central part of the design. Each Live Lab run creates an application-owned folder similar to:

<system temp>/PraatAudioToolsLiveLab/
  session_YYYYMMDD_HHMMSS_PID_RANDOM/
    owner.json
    session.lock
    captures/
    jobs/
    Live_Lab_Worker.praat

The Python process holds an OS-level lock while the session is active. Each Praat worker writes its own temporary files inside its job folder (the worker's TEMP, TMP and TMPDIR are redirected there). The manager removes an individual job folder after success or failure; the session folder is removed on clean shutdown.

On Windows, the implementation protects workers with a Job Object configured to terminate assigned processes when it closes. On other supported environments it uses a process group. On ordinary closure it disarms capture, stops and closes audio/MIDI resources, cancels and reaps processing workers, waits for the capture writer, clears the Bank and removes the session workspace.

The Praat entry point also creates short-lived, app-prefixed launch-handshake files in the operating system's temporary directory. They are removed on normal completion; stale matching files are subject to later recovery. Do not manually delete an active session folder, as its files may still be in use.

Diagnostics and troubleshooting

The Diagnostics tab shows the active workspace path, a temporary in-memory activity log, the running Praat worker PID when available, Inspect workspace and Cancel all processing. Cancellation does not mean that audio already playing must stop.

Compositional performance workflows

Installation and requirements

Recommended file placement:

plugin_AudioTools/
  py/
    Live_Lab.praat
    live_lab.py
  Vector Chain/
    Live_1.praat
    Live_2.praat
    Live_3.praat
    Live_4.praat
    Live_5.praat
    Live_6.praat
    Live_1_Random.praat
    Live_2_Random.praat
    Live_3_Random.praat
  ... (the existing processing modules)

The Praat entry script may alternatively reside in Vector Chain/; it searches for live_lab.py beside itself and then in py/. The preferred layout above keeps the application and launcher side by side, as in the existing Performance Launcher.

Install missing packages in the same interpreter selected by the launcher:

python -m pip install numpy sounddevice soundfile
python -m pip install python-rtmidi  # optional MIDI input

tkinter is ordinarily supplied with common Python distributions but may need separate installation on some systems. The launcher first probes the user-home virtual environment named praat_ddsp_env, then alternative Python executables. If your environment uses a different name, edit pyVenvName$ near the start of Live_Lab.praat. The launcher reports missing dependencies and does not install them silently.

Limitations and performance considerations

• Not a sample-by-sample live effect: capture ends before Praat can render the resulting one-shot. Rendering time depends on the chain, sample duration and computer.
• Single worker: only one Praat job runs at once; later recordings queue in FIFO order. A heavy chain can delay newer material even while playback remains available.
• Stereo captures process as Mono: original Stereo input is retained for export, but the current Live adapters feed a Mono signal to the original chains.
• Output channels are limited: defined result-routing counts are 1, 2 or 8; an eight-channel result cannot play in the default Stereo profile until an explicit downmix is selected.
• Manual and Auto have different musical guarantees: AUTO is subject to Latest Capture Priority and may leave a late result READY, even when its source chain is configured AUTO.
• No looping: every triggered result is One-Shot; repeated playback is a new user action.
• Limited RAM and capture buffering: long results and overlapping voices increase memory/CPU cost. Bank capacity and memory budgets are finite; active/protected entries may prevent further captures.
• Audio-device changes are disruptive: full-duplex ASIO streams are hardware-dependent. Check routing, block size and stability on the actual performance machine.
• Output protection changes peaks when engaged: the limiter is a performance safeguard, not a mastering tool. Test transients and gain staging on the intended speakers.
• Crash recovery is not instantaneous: forced termination or power loss may leave a locked or pending workspace until the next safe recovery opportunity.
• Results are not permanently archived by default: explicitly Export selected material you wish to keep.
• Hardware validation still matters: simulated or Linux headless tests do not replace a complete Windows/ASIO/MIDI sound-check and repeated clean-shutdown test.

Practical recommendation: begin with one short manually triggered take, validate capture and routing, then activate AUTO one chain at a time. Use Diagnostics after any failed job, and keep Auto Suspend and Stop All accessible on stage.