Repository navigation
Docs: analyze partial status, analyze batch, moments extended measurement - #34
Merged
Merged
Conversation
…ment Document three recoupable/api changes in the OpenAPI source, reference pages and credits page: - POST /api/songs/analyze: full_report status "success" | "partial" with failed[], 502 bodies (rejected call with upstream_status/detail, every section failed with failed[]), M4A/AAC/OGG/WebM input, request and response examples, and a "which to use" guide. Drops the third-party model name and link from the operation description. - POST /api/songs/analyze/batch (new, pending): up to 40 prompts on one audio download, one base price plus seconds. - POST /api/songs/moments (new page, pending): sections and moments measured from the audio, tempo_hint, and the extended measurement fields. Regenerated manifest, navigation, inventory, llms-full.txt, the operation inventory (the two new operations are recorded as pending) and the shared example-cases fixture hashes for releases.json and credits.mdx. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
 |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
7 issues found across 12 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="content/docs/source/api-reference/songs/analyze.mdx">
<violation number="1" location="content/docs/source/api-reference/songs/analyze.mdx:10">
P3: These recommendations present the batch and moments endpoints as available, but both linked operations are still pending and not callable in production. Qualify the guidance with “once released” so readers do not switch to unavailable endpoints.</violation>
<violation number="2" location="content/docs/source/api-reference/songs/analyze.mdx:16">
P2: The documented 502 example serializes `detail` as a JSON object string, so it does not begin with `audio_unreachable` or `audio_undecodable` as this page claims. Document the nested `detail` value or tell clients to parse the response text before checking the cause.</violation>
</file>
<file name="content/docs/source/api-reference/songs/analyze-batch.mdx">
<violation number="1" location="content/docs/source/api-reference/songs/analyze-batch.mdx:36">
P2: `elapsed_seconds` is wall time for the whole batch, including audio download, not total inference time. Describe it as the billable elapsed time including download so users can estimate the charge correctly.</violation>
</file>
<file name="content/docs/source/api-reference/songs/moments.mdx">
<violation number="1" location="content/docs/source/api-reference/songs/moments.mdx:15">
P2: This description implies all three cut lengths are always available, but the API omits lengths that do not fit inside a short song. Qualify the statement so clients do not assume `cuts["30"]` always exists.</violation>
<violation number="2" location="content/docs/source/api-reference/songs/moments.mdx:43">
P3: `lufs` can be a mono-mix estimate when the loudness meter cannot read the file, so describing it as stereo loudness is inaccurate. Document that fallback.</violation>
<violation number="3" location="content/docs/source/api-reference/songs/moments.mdx:49">
P3: The `band_profile` row leaves `side_pct` undefined. State that it is side energy as a percentage of that band’s mid energy so consumers can interpret the value.</violation>
<violation number="4" location="content/docs/source/api-reference/songs/moments.mdx:57">
P3: `tempo_note` can report that `tempo_hint` overruled the tracker, but this row omits that outcome. Include it so callers can distinguish reconciliation from replacement.</violation>
</file>
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
|
|
||
| ## Audio formats | ||
|
|
||
| `audio_url` accepts MP3, WAV, FLAC, M4A, AAC, OGG and WebM. The format is read from the file extension in the URL path, so give the URL a real extension; a URL without one is treated as MP3. If the model service cannot fetch the file or cannot read it as audio, a single preset or prompt call answers `502` with `upstream_status` `422` and a `detail` beginning `audio_unreachable` or `audio_undecodable`. A `full_report` fails every section the same way and answers `502` with `failed`. |
There was a problem hiding this comment.
P2: The documented 502 example serializes detail as a JSON object string, so it does not begin with audio_unreachable or audio_undecodable as this page claims. Document the nested detail value or tell clients to parse the response text before checking the cause.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/songs/analyze.mdx, line 16:
<comment>The documented 502 example serializes `detail` as a JSON object string, so it does not begin with `audio_unreachable` or `audio_undecodable` as this page claims. Document the nested `detail` value or tell clients to parse the response text before checking the cause.</comment>
<file context>
@@ -2,3 +2,57 @@
+
+## Audio formats
+
+`audio_url` accepts MP3, WAV, FLAC, M4A, AAC, OGG and WebM. The format is read from the file extension in the URL path, so give the URL a real extension; a URL without one is treated as MP3. If the model service cannot fetch the file or cannot read it as audio, a single preset or prompt call answers `502` with `upstream_status` `422` and a `detail` beginning `audio_unreachable` or `audio_undecodable`. A `full_report` fails every section the same way and answers `502` with `failed`.
+
+## Partial full reports
</file context>
Suggested change
| `audio_url` accepts MP3, WAV, FLAC, M4A, AAC, OGG and WebM. The format is read from the file extension in the URL path, so give the URL a real extension; a URL without one is treated as MP3. If the model service cannot fetch the file or cannot read it as audio, a single preset or prompt call answers `502` with `upstream_status` `422` and a `detail` beginning `audio_unreachable` or `audio_undecodable`. A `full_report` fails every section the same way and answers `502` with `failed`. | |
| `audio_url` accepts MP3, WAV, FLAC, M4A, AAC, OGG and WebM. The format is read from the file extension in the URL path, so give the URL a real extension; a URL without one is treated as MP3. If the model service cannot fetch the file or cannot read it as audio, a single preset or prompt call answers `502` with `upstream_status` `422` and a `detail` response containing a nested cause beginning `audio_unreachable` or `audio_undecodable`. A `full_report` fails every section the same way and answers `502` with `failed`. |
|
|
||
| ## Pricing | ||
|
|
||
| `$0.05` once per batch plus `$0.001166` per second of the batch's total inference time, which is the response's top-level `elapsed_seconds`. It is charged once, after the batch succeeds, as a single usage row. For example, a batch that runs 90 seconds costs `$0.15494`. The balance must hold `$0.05` before the model runs; otherwise the response is `402` and nothing is charged. A batch the model service rejects is not charged. See [Credits](/credits). |
There was a problem hiding this comment.
P2: elapsed_seconds is wall time for the whole batch, including audio download, not total inference time. Describe it as the billable elapsed time including download so users can estimate the charge correctly.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/songs/analyze-batch.mdx, line 36:
<comment>`elapsed_seconds` is wall time for the whole batch, including audio download, not total inference time. Describe it as the billable elapsed time including download so users can estimate the charge correctly.</comment>
<file context>
@@ -0,0 +1,36 @@
+
+## Pricing
+
+`$0.05` once per batch plus `$0.001166` per second of the batch's total inference time, which is the response's top-level `elapsed_seconds`. It is charged once, after the batch succeeds, as a single usage row. For example, a batch that runs 90 seconds costs `$0.15494`. The balance must hold `$0.05` before the model runs; otherwise the response is `402` and nothing is charged. A batch the model service rejects is not charged. See [Credits](/credits).
</file context>
Suggested change
| `$0.05` once per batch plus `$0.001166` per second of the batch's total inference time, which is the response's top-level `elapsed_seconds`. It is charged once, after the batch succeeds, as a single usage row. For example, a batch that runs 90 seconds costs `$0.15494`. The balance must hold `$0.05` before the model runs; otherwise the response is `402` and nothing is charged. A batch the model service rejects is not charged. See [Credits](/credits). | |
| `$0.05` once per batch plus `$0.001166` per second of the batch's elapsed time, including audio download, which is the response's top-level `elapsed_seconds`. It is charged once, after the batch succeeds, as a single usage row. For example, a batch that runs 90 seconds costs `$0.15494`. The balance must hold `$0.05` before the model runs; otherwise the response is `402` and nothing is charged. A batch the model service rejects is not charged. See [Credits](/credits). |
|
|
||
| ## Which to use | ||
|
|
||
| Use this endpoint when you need to know when things happen in a song and how it measures: where the sections and best moments start and end, ready-made 6, 15 and 30 second cuts on the beat grid, loudness and peaks, the spectrum, key, and where to cut in and out. Those times and numbers come from measuring the audio, so they are repeatable. |
There was a problem hiding this comment.
P2: This description implies all three cut lengths are always available, but the API omits lengths that do not fit inside a short song. Qualify the statement so clients do not assume cuts["30"] always exists.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/songs/moments.mdx, line 15:
<comment>This description implies all three cut lengths are always available, but the API omits lengths that do not fit inside a short song. Qualify the statement so clients do not assume `cuts["30"]` always exists.</comment>
<file context>
@@ -0,0 +1,68 @@
+
+## Which to use
+
+Use this endpoint when you need to know when things happen in a song and how it measures: where the sections and best moments start and end, ready-made 6, 15 and 30 second cuts on the beat grid, loudness and peaks, the spectrum, key, and where to cut in and out. Those times and numbers come from measuring the audio, so they are repeatable.
+
+Use [`POST /api/songs/analyze`](/api-reference/songs/analyze) for judgments that need a listener: genre, mood, lyrics, mix feedback, sync fit. A single preset, `full_report` or a custom prompt answers one analysis at a time.
</file context>
Suggested change
| Use this endpoint when you need to know when things happen in a song and how it measures: where the sections and best moments start and end, ready-made 6, 15 and 30 second cuts on the beat grid, loudness and peaks, the spectrum, key, and where to cut in and out. Those times and numbers come from measuring the audio, so they are repeatable. | |
| Use this endpoint when you need to know when things happen in a song and how it measures: where the sections and best moments start and end, ready-made 6, 15 and 30 second cuts when those lengths fit the song, on the beat grid, loudness and peaks, the spectrum, key, and where to cut in and out. Those times and numbers come from measuring the audio, so they are repeatable. |
|
|
||
| Use this endpoint for one analysis of one song: a curated `preset` such as `mood_tags` or `catalog_metadata`, `preset: "full_report"` for all 13 sections at once, or a custom `prompt` for a single free-form question. | ||
|
|
||
| Use [`POST /api/songs/analyze/batch`](/api-reference/songs/analyze-batch) when you have many short questions about the same file. The audio is downloaded once and the base price is paid once for the whole batch instead of once per question. |
There was a problem hiding this comment.
P3: These recommendations present the batch and moments endpoints as available, but both linked operations are still pending and not callable in production. Qualify the guidance with “once released” so readers do not switch to unavailable endpoints.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/songs/analyze.mdx, line 10:
<comment>These recommendations present the batch and moments endpoints as available, but both linked operations are still pending and not callable in production. Qualify the guidance with “once released” so readers do not switch to unavailable endpoints.</comment>
<file context>
@@ -2,3 +2,57 @@
+
+Use this endpoint for one analysis of one song: a curated `preset` such as `mood_tags` or `catalog_metadata`, `preset: "full_report"` for all 13 sections at once, or a custom `prompt` for a single free-form question.
+
+Use [`POST /api/songs/analyze/batch`](/api-reference/songs/analyze-batch) when you have many short questions about the same file. The audio is downloaded once and the base price is paid once for the whole batch instead of once per question.
+
+Use [`POST /api/songs/moments`](/api-reference/songs/moments) when you need to know when things happen and how the audio measures: the song's sections, its best short moments with 6, 15 and 30 second cuts, loudness, spectrum, key and edit points. Those times and numbers are measured from the audio, not generated.
</file context>
| | `mute_drops` | Sudden drops in level: a `mute` is under two beats (a zero-bleed cut), a `breakdown` is two beats or more. Each has `start`, `end`, `beats`, `depth_db` and `mmss`. | | ||
| | `chord_loop` | The most common four-bar chord cycle, `dominant_loop`, with `loop_share`, `distinct_chords` and `bars`. `confidence` is always `low`; treat it as one estimate, not a transcription. | | ||
| | `edit_points` | Typed `in` and `out` points with a `name`, a `note` and `mmss`: the cold open, chorus entries and exits, the deepest mutes, breakdowns and their re-entry, and where a fade begins. | | ||
| | `tempo_note` | How `tempo_bpm` was decided: the beat tracker alone, or reconciled to `tempo_hint`. | |
There was a problem hiding this comment.
P3: tempo_note can report that tempo_hint overruled the tracker, but this row omits that outcome. Include it so callers can distinguish reconciliation from replacement.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/songs/moments.mdx, line 57:
<comment>`tempo_note` can report that `tempo_hint` overruled the tracker, but this row omits that outcome. Include it so callers can distinguish reconciliation from replacement.</comment>
<file context>
@@ -0,0 +1,68 @@
+| `mute_drops` | Sudden drops in level: a `mute` is under two beats (a zero-bleed cut), a `breakdown` is two beats or more. Each has `start`, `end`, `beats`, `depth_db` and `mmss`. |
+| `chord_loop` | The most common four-bar chord cycle, `dominant_loop`, with `loop_share`, `distinct_chords` and `bars`. `confidence` is always `low`; treat it as one estimate, not a transcription. |
+| `edit_points` | Typed `in` and `out` points with a `name`, a `note` and `mmss`: the cold open, chorus entries and exits, the deepest mutes, breakdowns and their re-entry, and where a fade begins. |
+| `tempo_note` | How `tempo_bpm` was decided: the beat tracker alone, or reconciled to `tempo_hint`. |
+
+<Note>
</file context>
Suggested change
| | `tempo_note` | How `tempo_bpm` was decided: the beat tracker alone, or reconciled to `tempo_hint`. | | |
| | `tempo_note` | How `tempo_bpm` was decided: the beat tracker alone, reconciled to `tempo_hint`, or overruled by `tempo_hint`. | |
| | `broadcast_ready` | `true` when the true peak is at or under -1 dBTP and the loudness is between -16 and -7 LUFS. `null` when the true peak is unknown. | | ||
| | `stereo` | `lr_correlation` between the channels (1 is identical) and `side_to_mid` (0 is mono). | | ||
| | `spectral_centroid_hz`, `rolloff95_hz` | Brightness: the mean centroid, and the frequency under which 95% of the energy lies. | | ||
| | `band_profile` | Seven bands, `sub` to `air`. Each has `share_pct` of the mix's energy (the seven add up to about 100), `side_pct`, `level_pct` against a typical pop split (50 is on the reference) and `status`: `clear` within 4 dB of it, `heavy` above, `light` below. | |
There was a problem hiding this comment.
P3: The band_profile row leaves side_pct undefined. State that it is side energy as a percentage of that band’s mid energy so consumers can interpret the value.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/songs/moments.mdx, line 49:
<comment>The `band_profile` row leaves `side_pct` undefined. State that it is side energy as a percentage of that band’s mid energy so consumers can interpret the value.</comment>
<file context>
@@ -0,0 +1,68 @@
+| `broadcast_ready` | `true` when the true peak is at or under -1 dBTP and the loudness is between -16 and -7 LUFS. `null` when the true peak is unknown. |
+| `stereo` | `lr_correlation` between the channels (1 is identical) and `side_to_mid` (0 is mono). |
+| `spectral_centroid_hz`, `rolloff95_hz` | Brightness: the mean centroid, and the frequency under which 95% of the energy lies. |
+| `band_profile` | Seven bands, `sub` to `air`. Each has `share_pct` of the mix's energy (the seven add up to about 100), `side_pct`, `level_pct` against a typical pop split (50 is on the reference) and `status`: `clear` within 4 dB of it, `heavy` above, `light` below. |
+| `fingerprint` | Six axes from 0 to 1: `organic_electronic`, `sparse_dense`, `dark_bright`, `intimate_anthemic`, `smooth_textured`, `slow_fast`. 0 is the left label, 1 the right. `fingerprint_inputs` holds the raw measurements. |
+| `key` | `tonic`, `mode` (`major` or `minor`) and `confidence`, a correlation up to 1. |
</file context>
Suggested change
| | `band_profile` | Seven bands, `sub` to `air`. Each has `share_pct` of the mix's energy (the seven add up to about 100), `side_pct`, `level_pct` against a typical pop split (50 is on the reference) and `status`: `clear` within 4 dB of it, `heavy` above, `light` below. | | |
| | `band_profile` | Seven bands, `sub` to `air`. Each has `share_pct` of the mix's energy (the seven add up to about 100), `side_pct` of that band's mid energy, `level_pct` against a typical pop split (50 is on the reference) and `status`: `clear` within 4 dB of it, `heavy` above, `light` below. | |
|
|
||
| | Field | Meaning | | ||
| | --- | --- | | ||
| | `lufs` | Integrated loudness of the stereo file, in LUFS. Same figure as `loudness_lufs`. | |
There was a problem hiding this comment.
P3: lufs can be a mono-mix estimate when the loudness meter cannot read the file, so describing it as stereo loudness is inaccurate. Document that fallback.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/songs/moments.mdx, line 43:
<comment>`lufs` can be a mono-mix estimate when the loudness meter cannot read the file, so describing it as stereo loudness is inaccurate. Document that fallback.</comment>
<file context>
@@ -0,0 +1,68 @@
+
+| Field | Meaning |
+| --- | --- |
+| `lufs` | Integrated loudness of the stereo file, in LUFS. Same figure as `loudness_lufs`. |
+| `true_peak_dbtp`, `loudness_range_lu` | True peak and loudness range. `null` when the loudness meter could not read the file. |
+| `sample_peak_dbfs`, `crest_factor_db` | Highest sample level, and that peak minus the average level. |
</file context>
Suggested change
| | `lufs` | Integrated loudness of the stereo file, in LUFS. Same figure as `loudness_lufs`. | | |
| | `lufs` | Integrated loudness in LUFS, normally measured from the stereo file. Same figure as `loudness_lufs`; when the loudness meter cannot read the file, it is estimated from the mono mix. | |
…moments Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Documents three API changes. These pages should merge after the API PRs they describe.
POST /api/songs/analyze:full_reportreturnsstatus: "success" | "partial"withfailed[], 502 bodies, M4A/AAC/OGG/WebM inputanalyzereference page and OpenAPI: updated schemas, 502 response, request/response examples, report-key retry tablePOST /api/songs/analyze/batch: up to 40 prompts on one audio download, one base price plus secondsanalyze-batchpage and OpenAPI operationPOST /api/songs/momentsgainstempo_hintand the extended measurementmomentspage and OpenAPI operation (the endpoint had no page yet)Each of the three pages has a short "Which to use" section (single preset vs batch vs moments). Pricing lines match the single-call wording already in the docs:
$0.05per model call plus$0.001166per second; batch pays the base once; moments is$0.01per song plus the analyze rate per described moment ($0.36gate with the defaultdescribe: true).credits.mdxhas rows for both new endpoints.Request and response examples were checked against the code: Zod messages and paths for the 400 examples, the credit gates for the 402 examples, the tempo reconcile text, and the edit-point names and notes. The moments response example is a synthetic song whose sections, moments, cuts, bands, fingerprint and edit points are consistent with each other.
Before merging
x-recoup-availability: pending(the contract inventory records them as unmatched, pending) and a pending warning on their pages. Remove both once the API PRs are merged and the pin below is refreshed.releases.jsonandcredits.mdx, whose hashes are recorded incontent/docs/contracts/example-cases.json. Thebuild-contract-examples.py --checkstep compares that file withlib/contracts/fixtures/published-docs.jsonin the pinned API checkout, so it stays red until the API repo carries the same file andapiSourceCommitinoperation-inventory.jsonis bumped to the merged commit. The file to copy is this PR'scontent/docs/contracts/example-cases.json. Then re-runpython3 scripts/refresh-contract-inventory.py --api <checkout>andpnpm docs:build.codex/analyze-m4awas deleted when #1226 merged); the docs describe its contract from branchcodex/analyze-batchat 51c2b873.Also changed
The
analyzeoperation description no longer names the third-party model or links its announcement; it says "an audio language model".Checks
pnpm docs:build,pnpm docs:check,pnpm test(145),pnpm type-check,pnpm lint,pnpm buildall pass.refresh-contract-inventory.py --checkpasses against an API checkout at the pinned commit.build-contract-examples.py --checkpasses only against an API checkout whose fixture was refreshed (see above).🤖 Generated with Claude Code
Summary by cubic
Documents three API changes in the OpenAPI source, song reference pages, contract fixtures, and the credits page: partial
full_reportstatus onPOST /api/songs/analyze, the newPOST /api/songs/analyze/batchendpoint, and the extended measurement onPOST /api/songs/moments.Changes
analyzepage now coversstatus: "partial"withfailed[], 502 bodies, M4A/AAC/OGG/WebM input, and a table mapping each failed report section to the preset that retries it.analyze-batchandmomentspages document limits, moment types, measurement fields, and pricing that matches the existing single-call wording.x-recoup-availability) with page warnings until their API PRs merge, and theanalyzeoperation description no longer names the third-party model.apiSourceCommit) that serves batch and moments.Before merging
build-contract-examples.py --checkstays red until the pinned API checkout carries this PR'sexample-cases.json; theapiSourceCommitpin is already updated.Written for commit e6beec3. Summary will update on new commits.