# Spatial Audio Validation lambda

Validates Dolby Atmos masters against Apple's delivery requirements and Sony's operational QC. For
the validation checks, the single-pass render architecture, and the finding reference, see
[`src/atmos/README.md`](src/atmos/README.md).

## Lint, type-check, and test

```
docker compose run --rm --build lint-and-test
```

## Format and fix linting issues

```
docker compose run --rm --build fmt
```

## Validate an atmos + stereo pair

Accepts local paths, `http(s)://`, `file://`, or `s3://` URLs. S3 URLs require AWS credentials in the environment (e.g. via `awsume`).

Against the committed fixtures:

```
docker compose run --rm --build dev-validate-atmos \
  tests/fixtures/dolby_renderer_silent_2s.wav \
  tests/fixtures/silent_stereo_2s.wav
```

Against your own files — drop them into `dev/assets/` (the folder is committed but its contents are gitignored and dockerignored):

```
docker compose run --rm --build dev-validate-atmos dev/assets/my-atmos.wav dev/assets/my-stereo.wav
```

Against files on the web:

```
docker compose run --rm --build dev-validate-atmos https://example.com/a.wav https://example.com/s.wav
```

Against production assets in S3 (atmos + stereo pair for `track_unique_id=49566625`: atmos from the original upload in `prod-orcd-raw-assets`, stereo reference is the FLAC transcode in `prod-orcd-mezzanine-assets`):

```
docker compose run --rm --build dev-validate-atmos \
  s3://prod-orcd-raw-assets/56e6ff17_c795_48c8_9ad5_d055b7920842 \
  s3://prod-orcd-mezzanine-assets/f2e356d5_2aeb_4b5d_a8f4_bf9be449357c.flac
```

## Simulate the SFN spatial_audio_validation step

Drop in any SFN message body and see what the worker would return. Runs the full worker loop with real S3 (presigned URLs) and real mediainfo; SQS goes through moto-server, task protection and SFN callbacks are mocked. Requires AWS credentials in the environment (e.g. via `awsume`) for the S3 access.

```
docker compose run --rm --build dev-handle-task \
  '{"task_token":"local","asset_upload_type":"atmos","atmos_bucket":"prod-orcd-raw-assets","atmos_key":"56e6ff17_c795_48c8_9ad5_d055b7920842","stereo_reference_bucket":"prod-orcd-mezzanine-assets","stereo_reference_key":"f2e356d5_2aeb_4b5d_a8f4_bf9be449357c.flac"}'
```

Or pass a JSON file path:

```
docker compose run --rm --build dev-handle-task path/to/body.json
```

## IDE setup (optional)

Everything above runs in Docker; a host Python environment is not required to build, test, lint, or run the validator.

If your IDE (PyCharm, VS Code, etc.) needs a Python interpreter for autocomplete, navigation, and inline type checking, create a local `.venv/` from `uv.lock`:

```
UV_PYTHON_PREFERENCE=managed uv sync --frozen --group dev
```

Point your IDE at `./.venv/bin/python`. The venv is gitignored.

`UV_PYTHON_PREFERENCE=managed` overrides the `python-preference = "only-system"` in `pyproject.toml` so uv can download a managed Python 3.14 instead of requiring a system install. The Docker build still uses system Python — the override only applies to this single command.