Rendering a scene collection

A SceneCollection stores audio scenes that must be rendered before the mixed audio and clean speech target are available for downstream use. Rendering consists of two stages: device IR computation followed by audio convolution. Device IR computation combines spatial IRs with device transfer functions (DTFs) to produce device-specific IRs. Device IR computation can run either locally or on the cloud — see Remote device rendering below. Audio convolution is always performed locally.

The examples on this page assume you already have a SceneCollection. See Scene collection for instructions on building one.

Basic examples

Remote device rendering and filtering

If your scene collection uses a device and/or filters in the scene listener device specs, call start_remote_optimization() before rendering. This dispatches the device IR computation to the cloud and optionally shows a live progress view. Once remote processing is complete, device IRs are downloaded and cached on disk on demand — each scene fetches its IRs from the cache on first use, downloading any that aren't present yet.

scene_collection.start_remote_optimization()

Before triggering remote processing, call print_remote_optimization_token_cost() to print the quoted token cost:

scene_collection.print_remote_optimization_token_cost()

start_remote_optimization() returns as soon as the tasks have been submitted and the progress view closes. To block until processing is complete, call wait_for_device_render_processing() after it:

# show_progress=False suppresses the live view so the call returns immediately after submission.
scene_collection.start_remote_optimization(show_progress=False)

# Block the current thread until all remote device IR jobs have finished.
scene_collection.wait_for_device_render_processing()

When you render individual scenes by iterating over the collection and calling scene.render() directly, and start_remote_optimization() hasn't been called yet, device IR computation runs locally instead. Local computation downloads the spatial IRs and DTFs, combines them into device IRs on your machine, and caches the results to disk. Use remote rendering when the number of unique source–receiver–device-orientation combinations is large, or when local compute resources are limited.

info

You only need to call start_remote_optimization() once per collection. Subsequent renders reuse the cached device IRs automatically. SceneCollection.render() calls it for you if it hasn't been triggered yet, so you can omit the explicit call when using that method.

Full collection rendering

SceneCollection.render() renders every scene and stores the results in the collection's internal dataframe. Pass sampling_rate, render_mode, target_selection, and target_render_mode to control the output. You can call render() multiple times with different parameters — each set of results is stored under its own entry and identified by those parameters.

render_settings = {
    "sampling_rate": 32000,
    "render_mode": scene.RenderMode.DEVICE,
    "target_selection": "group_1",  # source group name, track index or track indices
    "target_render_mode": scene.TargetRenderMode.WET_MONO,
}

# Results are keyed by these parameters, so multiple render() calls can coexist.
scene_collection.render(**render_settings)

To store a second set of renders with different settings alongside the first:

render_settings_mono = {
    "sampling_rate": 16000,
    "render_mode": scene.RenderMode.MONO,
    "target_selection": "group_2",
    "target_render_mode": scene.TargetRenderMode.WET_MONO,
}

scene_collection.render(**render_settings_mono)

Rendered audio retrieval

After calling render(), retrieve the audio for any scene by its id using get_render(). Pass the same render parameters you used when rendering to select the correct entry.

# Pass the same render_settings used during render() to select the correct result entry.
scene_id = scene_collection[0].id
rendered = scene_collection.get_render(scene_id, **render_settings)

mixed  = rendered["noisy_audio"]    # AudioSignal — all sources mixed and convolved
target = rendered["clean_audio"]    # AudioSignal — target signal only

When the collection has only one set of renders, no render parameters are required:

rendered = scene_collection.get_render(scene_id)

Call plot() on any AudioSignal to inspect it:

mixed.playback()
mixed.plot()

Scene-by-scene rendering

You can iterate over the collection and render each AudioScene individually. Use this approach when you need to process each scene immediately rather than batching all renders upfront.

render_target() accepts a track index, a list of track indices, or a source group name as target_selection. When a group name or index list is given, each matching track is rendered individually and the results are summed. To select by tag, resolve the index first using get_track_indices_by_tag():

for audio_scene in scene_collection:
    mixed = audio_scene.render(
        sampling_rate=32000,
        render_mode=scene.RenderMode.DEVICE,
    )

    target = audio_scene.render_target(
        target_selection="group_1",
        sampling_rate=32000,
        render_mode=scene.TargetRenderMode.WET_MONO,
    )
    # mixed and target are AudioSignal objects — write to disk or pass to a model here

info

When iterating scene-by-scene and start_remote_optimization() hasn't been called, device IR computation runs locally. Call start_remote_optimization() before the loop to use cloud-side computation instead.

Separated track output

Pass output_separated_tracks=True to render() to store each source track as an individual rendered signal alongside the mixed output.

scene_collection.render(
    sampling_rate=32000,
    render_mode=scene.RenderMode.DEVICE,
    target_selection="conversation",
    target_render_mode=scene.TargetRenderMode.WET_MONO,
    output_separated_tracks=True,  # adds per-track renders alongside the mixed output
)

rendered = scene_collection.get_render(scene_collection[0].id, **render_settings)
separated = rendered["separated_track_audio"]   # list of AudioSignal — one per source track

SNR calculation

Pass calculate_snr=True to render() to compute the signal-to-noise ratio for each rendered scene and store it alongside the audio results. target_selection is required when using this option.

scene_collection.render(
    sampling_rate=32000,
    render_mode=scene.RenderMode.DEVICE,
    target_selection="conversation",
    target_render_mode=scene.TargetRenderMode.WET_MONO,
    calculate_snr=True,  # requires target_selection; SNR is computed after rendering
)

rendered = scene_collection.get_render(scene_collection[0].id, **render_settings)
snr = rendered["snr"]   # one value per output channel, in dB

The SNR is measured using the ITU-T P.56 active-speech level method. An activity mask is derived from the rendered target signal and applied to both the target and the combined noise before computing the ratio, so only intervals where the target is active contribute to the result. All non-target source tracks plus any device noise are treated as noise.

Windowed target output

Use WetMonoWindowed or WetDeviceWindowed in place of TargetRenderMode to trim late reverberation from the clean target. These windowed variants detect the direct-sound onset in the IR and apply a fade-out at a configurable offset from it.

scene_collection.render(
    sampling_rate=32000,
    render_mode=scene.RenderMode.DEVICE,
    target_selection="conversation",
    target_render_mode=scene.WetMonoWindowed,
)

Playback and export

After rendering, call playback() on an AudioSignal to listen to it directly in a notebook environment. To save the result to disk, use save() with a .wav or .hdf5 path.

mixed.playback()
mixed.save("output/mixed_scene_0.wav")

Render modes

Mixed audio render modes

RenderMode controls how source tracks are convolved when rendering the mixed audio signal:

• RenderMode.AUTO — uses DEVICE if a device is configured, otherwise falls back to MONO
• RenderMode.MONO — mono room impulse response, single-channel output
• RenderMode.SPATIAL — full spatial IR, multichannel output
• RenderMode.DEVICE — device-filtered IR, output channels match the device array
• RenderMode.NONE — no convolution, dry (anechoic) output

Target render modes

TargetRenderMode controls how the clean target signal is rendered:

• TargetRenderMode.DRY_MONO — anechoic, mono
• TargetRenderMode.FREE_FIELD_DEVICE — device-filtered, no room acoustics
• TargetRenderMode.WET_MONO — room-convolved, mono
• TargetRenderMode.WET_DEVICE — room-convolved, device-filtered

In addition to the TargetRenderMode values above, WetMonoWindowed and WetDeviceWindowed window the room-convolved target to crop late reverberation.