# spatial-asset-ingester

Ingest spatial (Dolby Atmos) audio files and metadata into the platform. Given a stereo release and its corresponding spatial release, this script:

1. Resolves the stereo `release_id` and `track_id` from ows-product and ows-track
2. Locates the spatial `.wav` file in the `{environment}-dolby-atmos-packager-alpha-input` S3 bucket
3. Uploads the spatial asset to ows-assets via [python-ows-assets-uploader](https://github.com/theorchard/python-ows-assets-uploader)
4. Creates a `track_spatial` record in ows-track linking the stereo track to its spatial ISRC

This script is run via a Jenkins job. AWS credentials are passed in as environment variables.

### Testing

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

### Updating dependencies

```bash
docker compose run --build --rm update-lockfile 
```

### Running

* Set AWS credentials with access to ECR and the target environment

**Single track:**

```bash
ENVIRONMENT=<qa|prod> \
STEREO_UPC=<STEREO_UPC> \
STEREO_ISRC=<STEREO_ISRC> \
SPATIAL_UPC=<SPATIAL_UPC> \
SPATIAL_ISRC=<SPATIAL_ISRC> \
docker compose run --build --rm app
```

**Bulk (CSV file):**

```bash
ENVIRONMENT=<qa|prod> \
BULK_SPATIAL_FILE=input.csv \
docker compose run --build --rm -v /path/to/input.csv:/var/app/input.csv app
```

The CSV must have the following headers: `STEREO_UPC`,`STEREO_ISRC`,`SPATIAL_UPC`,`SPATIAL_ISRC`.

### Environment Variables

| Variable | Required | Description                                          |
|----------|----------|------------------------------------------------------|
| `ENVIRONMENT` | yes | Target environment (`qa` or `prod`)                  |
| `STEREO_UPC` | yes (single mode) | UPC of the stereo release                            |
| `STEREO_ISRC` | yes (single mode) | ISRC of the stereo track                             |
| `SPATIAL_UPC` | yes (single mode) | UPC of the spatial release                           |
| `SPATIAL_ISRC` | yes (single mode) | ISRC of the spatial track                            |
| `BULK_SPATIAL_FILE` | yes (bulk mode) | Path to the CSV file inside the container            |
| `BULK_MAX_WORKERS` | no (bulk mode) | Number of concurrent rows to process. Defaults to 2. |

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Unexpected error |
| 2 | Stereo UPC not found in ows-product |
| 3 | Stereo ISRC not found on stereo UPC in ows-track |
| 4 | Spatial ISRC not found on spatial UPC in S3 |

In bulk mode, the overall exit code is always `1` if any row failed. Each failed row is printed with its individual error code in the summary.

**Bulk failure report format:**

```
3/5 row(s) completed successfully.
2 row(s) failed:
  [<SPATIAL_UPC>/<SPATIAL_ISRC>] (exit code <N>) <error message>
  [<SPATIAL_UPC>/<SPATIAL_ISRC>] (exit code <N>) <error message>
```