feat(music): return the seed fal used on the generation detail read

Merged
SW
3mo ago
+147-7

Prerequisite for the song detail dialog (recoupable/chat#1992 matrix).

What fal actually keeps

The dialog is meant to show "full settings from the API response". Checking fal before building it, only one of the four settings the form collects is recoverable:

SourceReturns
queue.result{ audio, seed, duration }
queue.statusstatus, request_id, response_url, status_url, cancel_url, logs, metrics
/requests/{id}/input, /requests/{id}/request405

num_inference_steps and guidance_scale are consumed at submit and never echoed anywhere. They are not retrievable, so this PR does not pretend otherwise: the response reports the settings that genuinely exist rather than implying we kept the rest. Storing them was considered and rejected in favour of keeping the table at 13 columns.

Change

GET /api/music/{id} gains seed, read live from fal through the stored fal_request_id โ€” the same sourcing already used for logs, and for the same reason: fal produced it, so a column of ours would be a second source of truth that could disagree. It is also genuinely unknowable at submit time when the caller leaves the seed blank and fal picks one.

fetchMusicSeed short-circuits unless the generation is completed. The detail read is polled throughout a render, and nothing has a seed until fal finishes, so the polling path keeps its single fal call and the second is spent only on the terminal read. The two fal reads run concurrently.

Never throws: a fal outage yields seed: null, not a failed request that would otherwise have succeeded.

Tests

12 new assertions, TDD (confirmed RED before implementing). 59/59 green across lib/music; tsc --noEmit and eslint clean.

  • seed read off the finished result, both data-wrapped and top-level shapes
  • no fal call while rendering, or when the generation never reached fal
  • outage swallowed to null
  • missing and non-numeric seeds rejected rather than passed through
  • handler merges seed, and reports it as null rather than omitting the field

Follow-up

docs#308 still documents organization_id, num_inference_steps, guidance_scale, mime_type, file_size_bytes, and title, none of which the API returns. A docs amendment follows separately.

๐Ÿค– Generated with Claude Code

https://claude.ai/code/session_017fSvwazBitPfsTQvVqpi8q


Summary by cubic

Returns the seed fal used on GET /api/music/{id} so the detail view shows actual run parameters. Previously the endpoint omitted seed; now it returns seed, with outages or unfinished renders yielding seed: null without failing the request.

  • Reads seed via fal.queue.result(MUSIC_MODEL) using the stored fal_request_id; only when status is completed; runs in parallel with logs.
  • Response always includes generation.seed (number|null); the field is present even when null.
  • Omits num_inference_steps and guidance_scale because fal never returns them; avoids a second source of truth.
  • No migration required; clients may display seed when available.

Summary by CodeRabbit

  • New Features

    • Music generation results now include the generation seed when available.
    • Generation logs and seed data are retrieved live and returned together.
  • Bug Fixes

    • Improved handling of unavailable, incomplete, or invalid generation requests and seeds.
    • Supports multiple result payload formats while safely returning unavailable seed values.