Music Generation Studio

Develop a theme, scene, lyric fragment, complete lyric, functional music brief,
or reference recording into one coherent musical direction and,
when the user wants audio, one intentional generation request. The deliverable
may be a song, instrumental, BGM, soundtrack, jingle, multilingual track, or
reference-led new arrangement. Treat singer identity, pronunciation, exact
duration, loop points, melody carryover, and mastering as qualities to review
after generation rather than guaranteed properties.

Lock genre, structure, and vocal or instrumental route before generation. A
“surprise me” random song is not this package's default. Route a cover or
re-arrangement of an existing recording to ai-song-cover-studio, a gift or
occasion song to personalized-song-maker, and a short loopable instrumental
for picture to short-video-bgm-studio.

The hard inputs are a theme or lyrics plus the intended use. If purpose,
genre, or vocal route is empty, gather them first; do not fill the gap with a
default pop brief.

Use the bundled scripts/mcp_client.py for every Beatra operation. Do not
configure or use a host Beatra Connector. Never use REST/OpenAPI as a fallback.
For ordinary calls, run
python3 scripts/mcp_client.py call and pass one JSON object on
stdin. For local files, use only the dedicated upload command described below.
See Bundled MCP Client diagnostics only when the
bundled path needs diagnosis.

Shape the direction first

Reuse every settled choice in the conversation. Infer ordinary creative details
from the destination when that is safe. Ask only when a missing answer changes
the lyrics, reference direction, vocal or instrumental route, exact paid payload,
or another high-impact user choice.

Before generation, prepare one compact production card:

• destination and listener;
• title, premise, emotional arc, primary genre, tempo feel, instrumentation,

structure, mix direction, ending or loop direction, and exclusions;

• vocal or instrumental route;
• full lyrics, language and register, and vocal direction when the track has

vocals;

• selected model and model-specific controls;
• reference intent and the qualities that should carry over or change when a

reference is involved; and

• the fact that the next action is one billable generation.

For instrumentals, omit lyrics and make room for dialogue or other functional
needs in the creative direction. For vocal music, finish and show material lyric
changes before generation. When lyrics exist, organize verse, chorus, and
bridge labels before paying. Do not put BPM, key, or tempo numbers into the
style caption. Lyrics writing, creative planning, model discovery,
prompt preparation, and critique do not require a paid music call. See
intent and routing,
creative brief and style,
lyrics craft, and
vocal, language, and tags.

When a brief uses artist shorthand, translate it into actionable genre, era,
tempo, instrumentation, harmony, vocal texture, phrasing, and mix attributes.

Choose and validate the model

Set model: "suno-5.5" for this package's ordinary generation. Never omit the
model and never silently use auto. Call beatra.models.list with capability
text_to_music or reference_audio_to_music when the user requests another
model, asks about current availability or price, or needs a model-specific
capability. Do not silently substitute a model.

Use only controls returned or documented for the selected model family. Suno
and MiniMax options are not interchangeable. Validate the exact payload using
model routing and use the examples in
music recipes as patterns rather than fixed
claims.

Use reference audio

For a local FLAC, MP3, or WAV reference, run only:

python3 scripts/mcp_client.py upload <path> --mime-type <type>

The bundled command obtains and validates the upload grant, uploads exactly the
file bytes, and returns the artifact to use as reference_audio. Do not replace
it with host HTTP, a connector, REST, or a hand-written grant and PUT sequence.
The general upload limit is 100 MB; the selected music model can impose a lower
size or duration limit.

Describe what should carry over and what should change. A reference guides a
new creative result; after generation, review melody, vocal character, energy,
instrumentation, and arrangement against that direction.

Confirm the paid boundary once

A direct, well-specified request to generate authorizes that exact request once.
Approval of the complete production card also authorizes it once. Do not add a
second confirmation. An estimate, comparison, lyric review, direction choice,
or “do not generate yet” is not approval.

Follow this golden path: lock structure and the dynamic arc, write an
executable caption plus labelled lyrics, then confirm one paid request that
produces a limited set of takes. After review, extend or replace only the
strongest section; do not automatically regenerate or chain Extend on the
whole song.

Before a billable call, make model, title, lyrics or instrumental status,
reference, important controls, and the one-generation scope visible. Create a
stable 1..128-character client_request_id only after that payload is final.
Any change to prompt, lyrics, instrumental flag, title, model, reference,
model options, or any other argument accepted by the current or a future MCP
generation schema is a new paid request with a new identity and confirmation.
Fields outside the published MCP schema are ignored and do not change the
request identity or task.

Let the bundled client perform its cached, best-effort, non-billable
beatra.installations.register step automatically. Do not add manual
registration to the creative workflow.

Submit beatra.music.generate once. Retain its task_id and poll the same task
with beatra.tasks.get. Honor a returned deadline_at; otherwise stop active
polling after 30 minutes, report the current state and how to resume, and do not
resubmit. Cancel only when the user asks via beatra.tasks.cancel; if cancel
conflicts with a terminal transition, return to the same task.

For an uncertain submission or lost task ID, search recent work with
beatra.tasks.list using the matching music capability. List results do not
contain the complete request: call beatra.tasks.get for each plausible
candidate and compare its task.input, resolved model, reference, and options
with the saved full payload. Only an exact identical retry may reuse the same
client_request_id. Never create replacement paid work merely because a
response was lost or a task is slow. See
tasks and results and
billing, errors, and recovery.

Deliver and review the music

On success, present every task.output.clips entry in returned order. Include
the returned title and lyrics when present plus clip.audio.url, artifact ID,
duration, MIME type, and size. Report factual task identity and
billing.net_charged_credits. When the task returns task.links.assets, use
that exact destination for asset management; do not invent a generic URL.

Review composition, lyrics, vocal performance, pronunciation, role assignment,
arrangement, ending, and production only when the host can actually play the
audio. Otherwise label listening review incomplete while still delivering the
factual artifacts. Preserve successful qualities and turn the largest gap into
one focused, newly approved generation. Follow
review and iteration.

References by task

• Intent, lyrics, instrumental, multilingual, and reference routes: intent and routing
• Brief, style, lyrics craft, vocal direction, and language: creative brief and style, lyrics craft, and vocal, language, and tags
• Current model selection and exact payload controls: model routing
• Request patterns and focused result review: music recipes and review and iteration
• First installation or expired authorization: installation and authentication
• Bundled command syntax and diagnostics: Bundled MCP Client diagnostics
• Task recovery, billing, and returned results: tasks and results and billing, errors, and recovery
• Automatic update behavior and persistent controls: automatic updates and safety
• Package removal and shared credential handling: uninstall and disconnect

Automatic updates and removal

Before ordinary Beatra commands, the bundled client silently checks for a
higher package version at most once every 24 hours. It uses the fixed official
discovery address and immutable official CDN source. It may automatically
install that higher version without separate confirmation. It verifies the
archive, manifest, and every packaged file, and replaces only
package-owned files. If checking, download, verification, replacement, or
recovery fails, the current installation stays usable and the original command
continues; an update failure never permits a paid retry.

The per-installation choice persists:

python3 scripts/mcp_client.py update --auto off
python3 scripts/mcp_client.py update --auto on
python3 scripts/mcp_client.py update --check

See automatic updates and safety
for the complete verified-update contract. For removal or credential cleanup,
follow uninstall and disconnect.
Never directly delete ~/.beatra or shared credentials because another Beatra
package may use the same connection.