Readspeech tutorial: README, tests, and lower audio data filter GPU defaults

[shubhamNvidia]

Summary

Documentation and testing for the readspeech audio tutorial, plus notebook hygiene and lighter default GPU fractions for the audio data filter pipeline.

Changes

Documentation & tutorial

• tutorials/audio/readspeech/README.md — Expanded guide, including A100 benchmark notes and workflow details.
• tutorials/audio/readspeech/readspeech_tutorial.ipynb — Added tutorial notebook for readspeech.

Tests

• tests/stages/audio/test_readspeech_create_initial_manifest.py — New tests for readspeech initial manifest creation.
• tests/stages/audio/test_common.py — Updates to shared audio stage tests.

Repo hygiene

• .gitattributes — *.ipynb uses nbstripout on commit to avoid large accidental notebook output diffs; notebook language hint preserved.

Default config

• nemo_curator/stages/audio/advanced_pipelines/audio_data_filter/default_config.yaml — Reduced default gpus for VAD, UTMOS, SigMOS, and speaker separation so defaults are less GPU-heavy out of the box (e.g. VAD 0.3 → 0.1, UTMOS/SigMOS 0.5 → 0.2, speaker separation 1.0 → 0.4).

Commits (vs main)

• Merge latest main into this branch.
• Docs: README benchmarks, notebook, tests, nbstripout.
• Lower default GPU fractions in audio data filter config.

Testing

• CI / existing audio stage tests
• Manual: follow README + notebook on target hardware if applicable

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[greptile-apps]

Greptile Summary

This PR adds a tutorial notebook and expanded README for the DNS Challenge ReadSpeech pipeline, new unit tests for manifest creation and audio common utilities, per-sample band-filter rejection logging, timing instrumentation in pipeline.py/run.py, and reduced default GPU fractions in default_config.yaml to lower out-of-the-box resource requirements. All changes are additive and self-contained with no breaking API modifications.

Confidence Score: 5/5

Safe to merge — only P2 style findings, no logic or correctness issues.

All findings are P2 (log level preference, minor log duplication). No correctness bugs, security issues, or data-integrity concerns were identified across any of the changed files.

No files require special attention.

Important Files Changed

Filename	Overview
nemo_curator/stages/audio/advanced_pipelines/audio_data_filter/default_config.yaml	Reduced default GPU fractions for UTMOS (0.2→0.1), SIGMOS (0.2→0.1), and speaker_separation (0.4→0.3) to lower out-of-the-box resource requirements.
nemo_curator/stages/audio/filtering/band.py	Added a logging call on band-filter rejection, but log level is info rather than debug, which will produce verbose output at scale.
tests/stages/audio/datasets/test_readspeech_create_initial_manifest.py	New test file covering manifest creation, filename parsing, sample limiting, end-to-end processing, and auto-download mocking — good coverage.
tests/stages/audio/test_common.py	Adds unit tests for audio utility helpers (ensure_mono, ensure_waveform_2d, load_audio_file, resolve_waveform_from_item, resolve_model_path) with appropriate mocking.
tutorials/audio/readspeech/README.md	Significantly expanded documentation: GPU memory requirements, performance benchmarks, parameter tuning guides, SIGMOS/UTMOS/VAD threshold explanations, composability notes, and troubleshooting tips.
tutorials/audio/readspeech/pipeline.py	Adds timing instrumentation and an extra info log; minor style issue with logger.exception duplicating {e} in the format string.
tutorials/audio/readspeech/run.py	Adds wall-clock timing log after pipeline.run(), consistent with the pipeline.py change.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[CreateInitialManifestReadSpeechStage] -->|AudioTask per WAV| B[MonoConversionStage]
    B --> C[VAD Segmentation]
    C --> D[BandFilterStage]
    D --> E[UTMOSFilterStage]
    E --> F[SIGMOSFilterStage]
    F --> G[SpeakerSeparationStage]
    G --> H[AudioToDocumentStage]
    H --> I[JsonlWriter]

    subgraph GPU Defaults Reduced
        E
        F
        G
    end

Loading

_{Reviews (24): Last reviewed commit: "chore: revert secrets baseline to upstre..." | Re-trigger Greptile}

[greptile-apps]

Duplicate *.ipynb pattern — consider merging into one line

There are now two separate *.ipynb attribute lines. Git applies both independently (different attributes don't collide), so it works correctly, but the convention is to keep all attributes for a single glob on one line to avoid confusion:

Suggested change

	*.ipynb filter=nbstripout
	*.ipynb linguist-language=Python filter=nbstripout

You can also remove the standalone comment line above if you merge them, or keep it as a line-comment above the combined entry.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[shubhamNvidia]

/ok to test 3122770

[sarahyurick]

Very nice, thanks! Left 2 open questions. I don't think they should block the PR, just want to make sure I understand.

[sarahyurick]

Just to double check, should we expect it to be 100% passing samples?

[shubhamNvidia]

It's expected to be 100% as it shows the total full band segment in output, it will be always 100% as we are filtering out the narrow band segments, I'm guessing u are confusing this with the overall band estimation

[sarahyurick]

Same here, should this be expected?

[mohammadaaftabv]

Suggested fix: Add a markdown cell between cells 8 and 9 explaining the discrepancy:

Note: With only 10 samples from a clean read-speech corpus, all samples pass the default thresholds.
On the full 14,279-sample dataset, the combined pass rate is ~23% — dominated by SIGMOS filtering
(OVRL ≥ 3.5, NOISE ≥ 4.0). To see realistic filtering behavior, increase MAX_SAMPLES to 500+.

[shubhamNvidia]

Added. Also corrected the assumption in the suggested text — with all 5 filters enabled (SIGMOS OVRL ≥ 3.5, NOISE ≥ 4.0), even 10 clean read-speech samples see a 30–70% rejection rate, so "near 100% pass rate" is not accurate. The note reads: "With MAX_SAMPLES = 10 the pass rate is highly variable. On the full 14,279-sample dataset the combined pass rate is ~23%, dominated by SIGMOS filtering. Increase MAX_SAMPLES to 500+ to see a more representative pass rate."

[mohammadaaftabv]

The README states:

Default GPU resource allocations total 0.9 GPU (0.1 + 0.2 + 0.2 + 0.4), allowing all stages to run concurrently on a single GPU.

But when speaker separation is enabled, AudioDataFilterStage.decompose() creates duplicate filter stages for the speaker-separated branch. The notebook's own execution plan confirms 15 stages including:

Main branch: VAD(0.1) + UTMOS(0.2) + SIGMOS(0.2) + SpeakerSep(0.4) = 0.9
Speaker branch: VAD_Speaker(0.1) + BandFilter_Speaker(0.0) + UTMOS_Speaker(0.2) + SIGMOS_Speaker(0.2) = 0.5
Total peak: 1.4 GPU
Ray's streaming executor won't fully schedule all stages concurrently, but the README's "0.9 GPU" claim is incomplete. Users on a single GPU with limited VRAM could hit OOM if Ray overlaps stages from both branches.

Suggested fix: Update to:

Default GPU allocations total 0.9 GPU for the main branch. When speaker separation is enabled, the duplicated filter stages for the speaker branch add another 0.5 GPU fraction (1.4 total). Ray's streaming executor manages scheduling to fit available resources, but users with limited GPU memory may need to reduce fractional allocations or disable speaker separation.

[shubhamNvidia]

Fixed in two places: (1) default_config.yaml GPU fractions reduced — UTMOS 0.2→0.1, SIGMOS 0.2→0.1, SpeakerSep 0.4→0.3 — so peak across both filter branches with speaker sep enabled is now 0.9 GPU (was 1.4). (2) README note updated to document that AudioDataFilterStage.decompose() instantiates a duplicated post-speaker filter branch, explain the GPU arithmetic, and link to default_config.yaml for tuning.

[shubhamNvidia]

/ok to test 8ffc99d

[shubhamNvidia]

/ok to test d496e74

[sarahyurick]

LGTM thanks!

[shubhamNvidia]

/ok to test 9b413f8

[sarahyurick]

Instead of using Ray directly, the tutorial can start with:

ray_client = RayClient()
ray_client.start()

and end with ray_client.stop().

[shubhamNvidia]

noted

[shubhamNvidia]

/ok to test fb89584

[shubhamNvidia]

/ok to test 2c2e97c

[shubhamNvidia]

/ok to test fc7c522

[copy-pr-bot]

/ok to test fc7c522

@shubhamNvidia, there was an error processing your request: E2

See the following link for more information: https://docs.gha-runners.nvidia.com/cpr/e/2/

[shubhamNvidia]

/ok to test d9851b1

[shubhamNvidia]

/ok to test 7b2fa1a

[shubhamNvidia]

/ok to test 67e23aa