The plan for all three parts is written before a single cent is spent. You read it, adjust whatever you want, approve each part individually — and only then generate. The cover and clip are free through Agnes; only the music uses credits.
Asking a generic agent to "make a song about X" gives you a random track, a cover that doesn't fit it, and no clip. The three come out disconnected because there was never a shared plan. Here, the plan is the product.
A plano.json with a closed schema decides the song structure, cover concept, and video breakdown together — using a style database measured from real material (BPM, key, instrumentation, vocal type).
Each part has its own cycle: ver → ajusta → ok → faz. You can stop after approving the cover and come back three days later — the estado.json pick up where you left off.
Pluggable provider using the adapter pattern + models.json declarative. Without a key, it appears unavailable with the reason — never runs over during generation. Switching is a flag.
Research is opt-in. The plan is free. Execution happens one part at a time, with the estimated cost shown before any call. Delivery is automatic when all three are ready.
Only with --pesquisa. It goes to the web to find niche references and see whether the topic has traction; it becomes pesquisa.md and is included as context for the planner. Never overwrites what you requested.
Zero media API cost. It comes plano.json (the contract) and PLANO.md (for you to read). The lyrics can be yours: like draft, it finishes and shows the diff; like final, is law and not even the adjuster touches it.
faz only runs what was approved. A provider failure doesn’t bring down the run: that part becomes erro with the message, and the others continue (exit 2).
Zero pip dependencies: everything uses the standard library. Keys are read at runtime from .env authorized and never copied into the repo.
python3 (3.10+) e ffmpeg, used to concatenate the clip's shots.
# Debian/Ubuntu sudo apt install ffmpeg
AGNES_API_KEY provides images and video at zero cost. It’s the default for both parts and the reason it runs on any VPS.
# read at runtime from: ~/projetos/openpcbotv2/.env
KIE_API_KEY (Suno v4.5), ~US$ 0,08 per generation — which already includes two tracks.
# read at runtime from: ~/projetos/wifi/.env
Real commands. The normal path uses the approval gate; there's a shortcut without the gate at the end for when you trust the plan.
Clone and go — no build or pip install.
git clone https://github.com/inematds/musicavideo.git && cd musicavideo
Free-form text request. The plan for all three parts is generated together, and the PLANO.md appears on screen.
bash musicavideo.sh plano "música de virada, rock feminino, sobre quem constrói em silêncio e agora cobra"
With no argument, it shows the full plan. With a part specified, it shows only that section — style and lyrics, cover concept and prompt, or the shot-by-shot breakdown.
bash musicavideo.sh ver agora-eu-cobro # the entire plan bash musicavideo.sh ver agora-eu-cobro clipe # just the shot breakdown
Replan just that part and prints a diff of what changed. As many times as you like — nothing has been generated yet.
bash musicavideo.sh ajusta agora-eu-cobro musica "mais lento, e o refrão sobe uma oitava"
Part without ok doesn’t generate. Approving one doesn’t approve the others.
bash musicavideo.sh ok agora-eu-cobro musica
Shows the estimated cost for each part and the total before before calling any API. Without that part, everything approved runs. --sim skips confirmation.
bash musicavideo.sh faz agora-eu-cobro musica # estimated cost: # music US$ 0.0800 (kie:suno-v4.5) # total US$ 0.0800 # confirm? [s/N]
As a draft, the planner finishes and shows the diff. With --letra-final, the lyrics are passed through verbatim and no one changes them — not even ajusta.
bash musicavideo.sh plano "sertanejo" --letra rascunho.txt bash musicavideo.sh plano "sertanejo" --letra final.txt --letra-final
Plan, approve all three, and execute. The limit keeps you from overspending: whatever fits gets completed; the rest remains approved and resumes with faz.
bash musicavideo.sh tudo "balada pop sobre recomeço" --teto 2 --sim
The engine lives in the plan, never in the code. The flag overrides it in plano, ajusta or faz.
bash musicavideo.sh faz agora-eu-cobro clipe --motor clipe=kling:kling-2.5
Each slug becomes a row in the index.jsonl, rewritten with every state change. The collection grows with each use and feeds its own planner.
bash musicavideo.sh lista 10 bash musicavideo.sh busca "rock" bash musicavideo.sh custo agora-eu-cobro # estimated vs. spent
There are two panels, and that's intentional. The local dashboard is the workbench: where you listen, compare, send things to the trash—and where you approves what comes out of the machine. A showcase is what the public sees. Uploading isn’t a consequence of being finished: production-ready work is working material.
A systemd service keeps the workbench running from boot on the local network. Going offline because you forgot to run the command is the bug, not the cost savings.
systemctl --user enable --now musicavideo-painelO publica-hf uploads only what changed, it writes the manifesto to the showcase repo and commits — publishing ends with the push, not halfway through.
bash musicavideo.sh publica-hf # 0 productions if nothing changed
The files live in a public dataset on Hugging Face, which serves range request — the video bar navigates directly, with no proxy or paid storage. The showcase only reads the manifest.
bash musicavideo.sh likes # the audience's ♥ comes back
The cover and clip defaults intentionally cost US$ 0 — that's what lets the project run on any VPS without an account anywhere.
kie:suno-v4.5 — ~US$ 0,08 per generation, provides 2 tracks. The only paid part today.
agnes:agnes-image-2.1-flash — US$ 0. Alternative: inemaimg:flux2-klein, local server on the DGX.
agnes:agnes-video-v2.0 — US$ 0, shots concatenated with ffmpeg. Paid alternatives: kling:kling-2.5 e fal:kling-video-v2.5-turbo-pro.
Adding a provider takes two files: providers/<nome>.py implementing disponivel/estimar_custo/gerar, e providers/<nome>.models.json declaring models, cost, and accepted params. Nothing else in the project changes.
# output for one slug ~/projetos/output/musicavideo/<slug>/ ├── plano.json # the contract ├── PLANO.md # the same plan, for you to read and approve ├── estado.json # source of truth: stages, cost, errors, history ├── faixa.mp3 capa.png clipe.mp4 ├── PACOTE.md # delivery (complete or partial, with what's missing) └── raw/ # raw provider responses
The core is complete and tested. What's missing is broader provider support and clip finishing.
plano.json is a closed contract precisely so other projects can consume it without knowing how it was made.