test: benchmark safe server-side audio level correction

[richiemcilroy]

Quiet Instant recordings need level correction, but voice processing is not yet proven to improve perceived quality consistently. This PR adds a disabled offline worker, reproducible benchmarks, aggregate results, and regression tests. It does not change production routes, desktop capture, playback, or original recordings. Live level correction requires a separately reviewed serving integration.

The proposed first audio rollout is bounded constant gain. The original 60-recording cohort was rerun after input hardening: 40 passed, 20 stayed unchanged, and every accepted output hash matched the earlier benchmark. Twenty full production MP4 files were also checked: one passed with exact video-packet proof and nineteen stayed unchanged. Customer media and transcripts are excluded from this PR.

Review fixes align STOI/SI-SDR on the same overlapping audio interval while retaining latency and unaligned metrics, restrict FFmpeg to local file protocols and media demuxers, bypass unsupported codecs, and prevent rejected candidates from entering the benchmark output set. EQ and denoising remain experimental.

Validation: 46 local tests / 148 assertions, two signal-alignment tests, scoped TypeScript and Biome, and Python syntax. The suites run in both production-image architectures and in the Railway image build. Production-sample measurements were made locally; they are not a full Linux cohort or subjective listening study. See apps/media-server/audio-quality-benchmarks.md for results, limitations, and the activation gates.

Final-head CI evidence (ee89503b2b929780621607e0504f16d95a269850): the Audio intelligibility alignment job passed on Ubuntu 24.04 with Python 3.12. Its log shows --only-binary=:all: downloading pystoi-0.4.1-py2.py3-none-any.whl, successfully installing all three pinned packages, then running both alignment tests successfully. The binary-only installation restriction is verified and remains in place.

Greptile Summary

This PR adds a disabled, offline audio-level correction worker, reproducible benchmark tooling and aggregate results, regression coverage for media safety and signal alignment, and CI validation across production-image architectures.

• Keeps production routes, playback, capture, and original recordings unchanged.
• Restricts processing to eligible local AAC media and validates timing, levels, stream preservation, and source integrity.
• Aligns intelligibility metrics over the same overlapping audio interval.
• Prevents rejected benchmark candidates from entering the retained output set.
• Runs the audio-quality and intelligibility regression suites in CI.

Confidence Score: 5/5

The PR appears safe to merge because no new changes were made after the previous review and the supplied final-head CI evidence disproves the remaining workflow-failure concern.

The three resolved findings remain addressed: aligned metrics use a shared overlapping interval, the documentation filename is kebab-case, and the alignment tests run from the applicable workflow. The remaining unresolved thread claimed that binary-only installation rejects pystoi 0.4.1, but the final-head Ubuntu CI run downloaded pystoi-0.4.1-py2.py3-none-any.whl, installed all pinned packages under --only-binary=:all:, and completed both alignment tests, so that finding is not outstanding.

Important Files Changed

Filename	Overview
apps/media-server/src/lib/audio-quality.ts	Implements the disabled shadow-only worker with bounded local input handling, source-integrity checks, rendering, output validation, and cleanup.
apps/media-server/src/lib/audio-quality-policy.ts	Defines conservative eligibility, gain-planning, and output-validation policies for level and experimental voice processing.
scripts/benchmark-audio-intelligibility.py	Computes aligned STOI and SI-SDR metrics while retaining latency and unaligned measurements.
.github/workflows/docker-build-media-server.yml	Adds CI coverage for alignment tests and audio-quality suites; the supplied final-head run confirms the pinned binary-only dependencies install and the tests pass.
apps/media-server/src/lib/audio-quality-benchmark.ts	Retains only validation-approved benchmark outputs and always cleans temporary candidates.
apps/media-server/audio-quality-benchmarks.md	Documents benchmark results, limitations, safety boundaries, reproduction steps, and activation gates.

_{Reviews (5): Last reviewed commit: "ci: set explicit media workflow token pe..." | Re-trigger Greptile}

[richiemcilroy]

hey @greptileai, please re-review the PR

[superagent-security]

Superagent found 3 security concern(s).

[superagent-security]

P1: Pin the checkout action to an immutable commit

CI runs mutable actions/checkout@v4 on pull requests and keeps checkout credentials by default.

Pin checkout to a reviewed SHA and set persist-credentials: false.

AI prompt

Check if this security scanner issue is valid. If so, understand the root cause and fix it. If appropriate, update or add tests. Keep the change focused and preserve intended behavior.

<file name=".github/workflows/audio-quality.yml">
<violation number="1" location=".github/workflows/audio-quality.yml:31">
<priority>P1</priority>
<title>Pin the checkout action to an immutable commit</title>
<evidence>The pull_request workflow executes actions/checkout@v4. A mutable tag allows a future action-repository change or tag movement to alter code execution in every run; checkout also retains its token credential by default.</evidence>
<recommendation>Replace actions/checkout@v4 with the full 40-character commit SHA and retain a version comment. Add persist-credentials: false because this test workflow does not push or call GitHub with the checkout credential.</recommendation>
</violation>
</file>

[superagent-security]

P2: Pin the CI container and system package inputs

The test job trusts a mutable Bun image tag and an unpinned FFmpeg apt package.

Pin the container by digest and use a verified, reproducible FFmpeg package source.

AI prompt

Check if this security scanner issue is valid. If so, understand the root cause and fix it. If appropriate, update or add tests. Keep the change focused and preserve intended behavior.

<file name=".github/workflows/audio-quality.yml">
<violation number="1" location=".github/workflows/audio-quality.yml:28">
<priority>P2</priority>
<title>Pin the CI container and system package inputs</title>
<evidence>The job uses the mutable oven/bun:1.4.0 image tag, then runs apt-get update and installs the unversioned ffmpeg package. A later registry or package-repository change can silently change the toolchain executing pull-request code.</evidence>
<recommendation>Pin the Bun container by digest and use a controlled, integrity-verified FFmpeg image or otherwise pin and verify the Debian package/repository snapshot. Record the expected versions as part of the reviewable toolchain definition.</recommendation>
</violation>
</file>

[richiemcilroy]

hey @greptileai, please re-review the PR

[superagent-security]

Superagent found 1 security concern(s).

[richiemcilroy]

hey @greptileai, please re-review the PR

[richiemcilroy]

hey @greptileai, please re-review the PR

[greptile-apps]

Binary-Only Install Rejects Pystoi

The new alignment job applies --only-binary=:all: to pystoi==0.4.1, but that version is distributed without a binary wheel. Pip therefore rejects the available source distribution, so this required CI job fails before the alignment tests can run.

Prompt To Fix With AI

This is a comment left during a code review.
Path: .github/workflows/docker-build-media-server.yml
Line: 50

Comment:
**Binary-Only Install Rejects Pystoi**

The new alignment job applies `--only-binary=:all:` to `pystoi==0.4.1`, but that version is distributed without a binary wheel. Pip therefore rejects the available source distribution, so this required CI job fails before the alignment tests can run.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[richiemcilroy]

hey @greptileai, please re-review the PR