Files
karaoke-gen/docs/archive/2026-09-26-unified-upload-flow-plan.md
Andrew Beveridge ☄️andClaude Opus 5.5 455fb11a14 feat(upload): unified browser upload flow, bring-your-own instrumental, stranded-upload cleanup (v0.243.0) (#1058)
## Summary
Two invisible upload failures on the same song led to this:
- **Job 8729f19a**: large audio upload (signed-URL flow) abandoned
mid-upload. The only UI signal was the "Creating..." button text and the
card already said "Setting up", so the job sat `pending` forever with
the credit spent.
- **Job 2d0c1ae0**: 44 MB instrumental upload on the review screen was a
multipart POST through Cloud Run (32 MiB cap) and failed silently. Only
the CORS preflight was logged.

## Changes
**Shared upload layer (frontend)**: all user uploads now go through one
path:
- `lib/upload.ts`: signed-URL PUT with progress, sequential multi-file
upload with aggregate progress, client-side duration check.
- `hooks/useUploadTask.ts`: progress state plus a `beforeunload` guard.
- `components/upload/UploadProgressModal.tsx`: a modal the user can't
close, showing progress, speed, ETA, "file N of M" and a keep-tab-open
warning.
- Used by guided job creation, tenant single job and instrumental
review. Tenant bulk keeps its per-row table and uses the shared guard.

**Guided flow**
- Always uses the signed-URL path, which also fixes
`requires_audio_edit` being silently dropped for uploads of 25MB or
more.
- Private upload jobs can attach their own instrumental
(`existing_instrumental`). This skips separation and instrumental
review. The duration is checked before upload, and the backing-vocals
option is hidden.

**Instrumental review**
- New `instrumental-upload-url` and `instrumental-upload-complete`
endpoints: direct-to-GCS upload, then a finalize step.
- One shared processing helper with the multipart route: duration check,
FLAC conversion, `stems.custom_instrumental`.
- Returns a signed `audio_url`. The old post-upload preview URL had no
backend route.
- Inline error plus toast for mismatches and failures.

**Backend robustness**
- `state_data.awaiting_upload`: the dashboard shows "Waiting for upload"
instead of "Setting up".
- The hourly stale-review run also cancels and refunds non-tenant jobs
still awaiting upload after 2h with nothing uploaded.
- `uploads-complete` now checks ownership (previously any signed-in user
could finalize any pending job). On an instrumental duration mismatch it
cancels and refunds the job instead of stranding it.

## Testing
- `make test`: backend 1839 + 4788 + 150 emulator passed; frontend Jest
1391 passed across 117 suites.
- New tests:
- backend: stale-upload processor; signed instrumental endpoints (15
cases); `requires_audio_edit` persistence; uploads-complete ownership
and cancel-on-mismatch
- frontend: upload lib, `useUploadTask`, modal (speed/ETA, can't be
dismissed), `OwnInstrumentalField`, `TenantJobFlow`, API flows
- Manual check against the real frontend (local dev, prod read-only;
create, upload and finalize endpoints mocked, uploads sent to a
throttled local PUT server, so no prod data was changed):
  - guided flow with and without an instrumental
- instrumental review upload on 2d0c1ae0, including a mismatch caught
before upload
- Escape and outside clicks don't close the modal; navigating away
triggers the `beforeunload` prompt

Plan: `docs/archive/2026-09-26-unified-upload-flow-plan.md`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-26 20:25:00 -04:00

2.6 KiB

Unified browser upload flow — plan (2026-09-26)

Why

  • Job 8729f19a: large audio upload (signed-URL flow) was silently abandoned — the only signal was the "Creating..." button text, and the job card already said "Setting up". The job sat PENDING forever with the credit spent.
  • Job 2d0c1ae0: instrumental-review "Alternate Instrumental" upload of a 44 MB WAV failed invisibly — it's a multipart POST through Cloud Run (32 MiB request cap), no progress, and the post-upload preview URL (/api/jobs/{id}/audio-stream/...) has no backend route.
  • Singer-songwriters with their own instrumental must currently go through vocal separation
    • instrumental review; existing_instrumental (tenant-only in the UI) already skips both.

Shared frontend upload layer (DRY)

  • lib/upload.ts: putFileToSignedUrl (XHR PUT, progress, clear errors), uploadFilesToSignedUrls (sequential multi-file, aggregate progress + current file), getAudioFileDuration (best-effort via <audio> metadata).
  • hooks/useUploadTask.ts: progress state + beforeunload guard while active; run(fn).
  • components/upload/UploadProgressModal.tsx: non-dismissable modal (progress, speed, ETA, file N of M, keep-tab-open warning); phase labels overridable per caller.
  • Used by: guided job creation, tenant single job, instrumental review upload. Tenant bulk keeps its per-row resumable table but uses the shared beforeunload hook.

Backend

  1. create-with-upload-urls accepts + persists requires_audio_edit (was silently dropped).
  2. uploads-complete: ownership check; on duration mismatch cancel the job (refund) so it can't be stranded, then return the 400.
  3. Instrumental review: POST /api/jobs/{id}/instrumental-upload-url → signed PUT to jobs/{id}/uploads/custom_instrumental_source{ext}; POST /api/jobs/{id}/instrumental-upload-complete → shared processing helper (duration check, FLAC, stems.custom_instrumental) and returns a signed audio_url for playback. Multipart endpoint kept (CLI/back-compat), same helper, also returns audio_url.
  4. Previous work: state_data.awaiting_upload, stale-upload sweep (cancel + refund after 2h).

Guided flow

  • Always use the signed-URL path (single code path; gets awaiting-upload label + cleanup).
  • Private + uploaded-audio jobs: optional "Use my own instrumental" file on the Customize step; client-side duration pre-check; sent as existing_instrumental.

Tests

Backend unit tests for new endpoints/fixes; Jest for upload lib, hook, modal, instrumental selector upload, guided-flow instrumental option; local Playwright run against the real frontend with a throttled PUT server.