@pixelvibing/cli 0.57.1 → 0.59.0

package/dist/pixel-vibing-cli.js

@@ -418,6 +418,66 @@ function apiAddress(environment = process.env) {
   if (!PLAIN_PATH.test(url.pathname)) throw new ApiAddressError("PIXELVIBING_API_URL's path may hold only letters, digits, and . _ ~ - /");
   return url.href.replace(/\/+$/, "");
 }
+const SFX_SECONDS = { min: 0.5, max: 22 };
+const MAX_SPEECH_CHARACTERS = 500;
+const MAX_AUDIO_DESCRIPTION = 600;
+const VOICES = [
+  "Aria",
+  "Roger",
+  "Sarah",
+  "Laura",
+  "Charlie",
+  "George",
+  "Callum",
+  "River",
+  "Liam",
+  "Charlotte",
+  "Alice",
+  "Matilda",
+  "Will",
+  "Jessica",
+  "Eric",
+  "Chris",
+  "Brian",
+  "Daniel",
+  "Lily",
+  "Bill"
+];
+const MUSIC_SECONDS = { min: 3, max: 600, unasked: 60 };
+const SECTION_SECONDS = { min: 3, max: 120 };
+const toMs = (seconds) => Math.round(seconds * 1e3) / 1e3;
+function musicSeconds(body) {
+  const sections = body.plan?.sections;
+  if (Array.isArray(sections))
+    return sections.reduce((sum, each) => sum + (typeof each?.seconds === "number" && Number.isFinite(each.seconds) ? toMs(each.seconds) : 0), 0);
+  return typeof body.seconds === "number" && Number.isFinite(body.seconds) ? toMs(body.seconds) : MUSIC_SECONDS.unasked;
+}
+function musicMinutes(body) {
+  return Math.max(1, Math.ceil(musicSeconds(body) / 60));
+}
+function musicProblem(body) {
+  const described = typeof body.description === "string" && body.description.trim() !== "";
+  if (body.plan === void 0) {
+    if (!described) return "describe the music, or give a composition plan";
+    if (body.seconds !== void 0 && !(typeof body.seconds === "number" && body.seconds >= MUSIC_SECONDS.min && body.seconds <= MUSIC_SECONDS.max))
+      return `music runs ${MUSIC_SECONDS.min} to ${MUSIC_SECONDS.max} seconds`;
+    return null;
+  }
+  if (body.description !== void 0) return "music takes a description or a composition plan, not both";
+  if (body.seconds !== void 0 || body.instrumental !== void 0)
+    return "a composition plan's length is its sections', and its lyrics say whether it is sung";
+  const sections = body.plan.sections;
+  if (!Array.isArray(sections) || sections.length === 0) return "a composition plan has at least one section";
+  for (const section2 of sections) {
+    const { name, seconds: seconds2 } = typeof section2 === "object" && section2 !== null ? section2 : {};
+    if (typeof name !== "string" || name.trim() === "") return "each section has a name";
+    if (!(typeof seconds2 === "number" && seconds2 >= SECTION_SECONDS.min && seconds2 <= SECTION_SECONDS.max))
+      return `a section runs ${SECTION_SECONDS.min} to ${SECTION_SECONDS.max} seconds, not ${String(seconds2)}`;
+  }
+  const seconds = musicSeconds(body);
+  if (seconds > MUSIC_SECONDS.max) return `a composition plan runs at most ${MUSIC_SECONDS.max} seconds in all, not ${seconds}`;
+  return null;
+}
 class GuideConflict extends Error {
   constructor(current) {
     super(`the style guide is now at version ${current}`);
@@ -433,6 +493,12 @@ class TooFewCredits extends Error {
     this.credits = credits;
   }
 }
+function costIn(prices, kind, body) {
+  const price = prices.kinds[kind];
+  if (price === void 0) return null;
+  if ("credits" in price) return price.credits;
+  return price.perMinute !== void 0 && body !== void 0 ? price.perMinute * musicMinutes(body) : price.upTo;
+}
 const id = (value) => encodeURIComponent(value);
 function createWebApi(fetcher = (input, init2) => fetch(input, init2), base = API_BASE) {
   const call = createCaller(fetcher, base);
@@ -447,9 +513,10 @@ function createWebApi(fetcher = (input, init2) => fetch(input, init2), base = AP
       throw error;
     }
   };
+  const address = new URL(base, globalThis.location?.origin ?? "http://localhost").href.replace(/\/+$/, "");
   return {
     /** The API's own address, whole, for the MCP server's next to it (specs/web-app/ R2.14). */
-    address: new URL(base, globalThis.location?.origin ?? "http://localhost").href.replace(/\/+$/, ""),
+    address,
     /** The project's own token, to the signed-in person alone (specs/accounts-and-sign-in/ R3.12). */
     projectToken: (projectId) => json2(`/projects/${id(projectId)}/token`),
     projects: (before = null) => json2(`/projects${before === null ? "" : `?before=${id(before)}`}`),
@@ -524,6 +591,8 @@ function createWebApi(fetcher = (input, init2) => fetch(input, init2), base = AP
     redo: (jobId) => paying2(async () => (await json2(`/jobs/${id(jobId)}/redo`, { method: "POST" })).id),
     /** Cancel a job no worker has taken, answering it and the credits that came back; 409 once one has (specs/generation-jobs/ R5). */
     cancelJob: (jobId) => json2(`/jobs/${id(jobId)}/cancel`, { method: "POST" }),
+    /** The address of a project's job changes, as server-sent events (specs/live-generations/ R1.3). */
+    jobEventsUrl: (projectId) => `${address}/jobs/events?project=${id(projectId)}`,
     jobs: (projectId, before = null, kinds = null) => json2(
       `/jobs?project=${id(projectId)}${before === null ? "" : `&before=${id(before)}`}${kinds === null ? "" : `&kinds=${kinds.map(id).join(",")}`}`
     ),
@@ -4887,12 +4956,14 @@ function shareWords(credits, limit) {
 function leftWords(usage) {
   return `${100 - usedPercent(usage)}% of your limit left`;
 }
-function costShareWords(prices, kind, usage) {
+function costShareWords(prices, kind, usage, body) {
   const price = prices.kinds[kind];
-  if (price === void 0) return null;
-  const most = "credits" in price ? price.credits : price.upTo;
+  const most = costIn(prices, kind, body);
+  if (price === void 0 || most === null) return null;
   const share = `${shareWords(most, usage.limit)} of your limit`;
-  return "credits" in price ? share : `up to ${share}, charged for what it uses once done`;
+  if ("credits" in price) return share;
+  if (price.perMinute !== void 0 && body !== void 0) return `${share}, by the minute of its length`;
+  return `up to ${share}, charged for what it uses once done`;
 }
 const LARGEST_FOOTPRINT = {
   cols: Math.min(Math.floor(WINDOW_PX.width / SCALES.at(-1)), Math.floor(MAX_ASSEMBLED_PX / TILE_SIZE)),
@@ -4914,31 +4985,6 @@ function drawCanvas(footprint) {
   if (pxPerTile === void 0) return null;
   return { width: footprint.cols * pxPerTile, height: footprint.rows * pxPerTile, pxPerTile };
 }
-const SFX_SECONDS = { min: 0.5, max: 22 };
-const MAX_SPEECH_CHARACTERS = 500;
-const MAX_AUDIO_DESCRIPTION = 600;
-const VOICES = [
-  "Aria",
-  "Roger",
-  "Sarah",
-  "Laura",
-  "Charlie",
-  "George",
-  "Callum",
-  "River",
-  "Liam",
-  "Charlotte",
-  "Alice",
-  "Matilda",
-  "Will",
-  "Jessica",
-  "Eric",
-  "Chris",
-  "Brian",
-  "Daniel",
-  "Lily",
-  "Bill"
-];
 const PATCH_CORNERS = [
   [1, 0, 0, 0, 0],
   [1, 0, 0, 1, 0],
@@ -5774,8 +5820,10 @@ const OWN_OPTIONS = {
   terrain: ["terrain-animation"],
   text: ["speech"],
   voice: ["speech"],
-  seconds: ["sfx"],
+  seconds: ["sfx", "music"],
   loop: ["sfx"],
+  instrumental: ["music"],
+  plan: ["music"],
   out: ["sfx", "speech", "music", "vfx"],
   preset: ["vfx"],
   part: ["vfx"],
@@ -5816,8 +5864,18 @@ const MORE_OPTIONS = {
   terrain: { type: "string", value: "<asset id|name>", description: "the terrain set an animated terrain set moves" },
   text: { type: "string", value: "<text>", description: "what speech says" },
   voice: { type: "string", value: "<voice>", description: `the voice speech is said in: ${VOICES.join(", ")}` },
-  seconds: { type: "string", value: "<seconds>", description: `a sound effect's length, ${SFX_SECONDS.min} to ${SFX_SECONDS.max}` },
+  seconds: {
+    type: "string",
+    value: "<seconds>",
+    description: `a sound effect's length, ${SFX_SECONDS.min} to ${SFX_SECONDS.max}; music's, ${MUSIC_SECONDS.min} to ${MUSIC_SECONDS.max}, ${MUSIC_SECONDS.unasked} unless given`
+  },
   loop: { type: "boolean", description: "a sound effect that loops seamlessly" },
+  instrumental: { type: "boolean", description: "music with no voice" },
+  plan: {
+    type: "string",
+    value: "<json>",
+    description: `music section by section, instead of --instruction: a JSON file of { styles, avoid, sections: [{ name, seconds (${SECTION_SECONDS.min}-${SECTION_SECONDS.max}), styles, avoid, lyrics }], flexibleLengths }, at most ${MUSIC_SECONDS.max} seconds in all`
+  },
   out: {
     type: "string",
     value: "<path>",
@@ -5992,9 +6050,9 @@ async function moreRequest(context, kind, args, instruction, reference) {
     if (!VOICES.includes(voice)) throw new CliError(`--voice is one of ${VOICES.join(", ")}`);
     return { kind, body: { text: text2, voice }, words: `${words} in ${voice}: ${text2}` };
   }
+  if (kind === "music") return musicRequestOf(context, args, instruction);
   if (instruction === "") throw new CliError(`describe ${words} with --instruction`);
   if (instruction.length > MAX_AUDIO_DESCRIPTION) throw new CliError(`a description is at most ${MAX_AUDIO_DESCRIPTION} characters`);
-  if (kind === "music") return { kind, body: { description: instruction }, words: `${words}: ${instruction}` };
   const seconds = stringOf(args, "seconds");
   const length = seconds === void 0 ? void 0 : Number(seconds);
   if (length !== void 0 && !(length >= SFX_SECONDS.min && length <= SFX_SECONDS.max))
@@ -6005,6 +6063,54 @@ async function moreRequest(context, kind, args, instruction, reference) {
     words: `${words}${length === void 0 ? "" : ` of ${length} s`}${flagOf(args, "loop") ? ", looping" : ""}: ${instruction}`
   };
 }
+const MAX_PLAN_BYTES = 128 * 1024;
+async function planOf(context, path) {
+  const file = resolve(context.io.cwd, path);
+  let text2;
+  try {
+    const found = await stat(file);
+    if (!found.isFile()) throw new CliError(`the plan ${path} is not a file`);
+    if (found.size > MAX_PLAN_BYTES) throw new CliError(`the plan ${path} is larger than ${MAX_PLAN_BYTES} bytes`);
+    text2 = await readFile(file, "utf8");
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError(`the plan ${path} cannot be read`);
+  }
+  let plan;
+  try {
+    plan = JSON.parse(text2);
+  } catch {
+    throw new CliError(`the plan ${path} is not JSON`);
+  }
+  if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+    throw new CliError(`the plan ${path} is not a plan: { "styles": [...], "sections": [{ "name": "intro", "seconds": 20 }] }`);
+  return plan;
+}
+async function musicRequestOf(context, args, instruction) {
+  const path = stringOf(args, "plan");
+  const given2 = stringOf(args, "seconds");
+  if (path !== void 0) {
+    if (instruction !== "") throw new CliError("music takes --instruction or --plan, not both");
+    if (given2 !== void 0 || flagOf(args, "instrumental"))
+      throw new CliError("a plan's length is its sections', and its lyrics say whether it is sung: --seconds and --instrumental are not a plan's");
+    const body = { plan: await planOf(context, path) };
+    const problem = musicProblem(body);
+    if (problem !== null) throw new CliError(`the plan ${path}: ${problem}`);
+    const sections = body.plan.sections.map((section2) => String(section2.name)).join(", ");
+    return { kind: "music", body, words: `music of ${musicMinutes(body)} min from ${path}: ${sections}` };
+  }
+  if (instruction === "") throw new CliError("describe the music with --instruction, or give its sections with --plan");
+  if (instruction.length > MAX_AUDIO_DESCRIPTION) throw new CliError(`a description is at most ${MAX_AUDIO_DESCRIPTION} characters`);
+  const seconds = given2 === void 0 ? void 0 : Number(given2);
+  if (seconds !== void 0 && !(seconds >= MUSIC_SECONDS.min && seconds <= MUSIC_SECONDS.max))
+    throw new CliError(`--seconds is ${MUSIC_SECONDS.min} to ${MUSIC_SECONDS.max} for music`);
+  const instrumental = flagOf(args, "instrumental");
+  return {
+    kind: "music",
+    body: { description: instruction, ...seconds === void 0 ? {} : { seconds }, ...instrumental ? { instrumental: true } : {} },
+    words: `music of ${seconds ?? MUSIC_SECONDS.unasked} s${instrumental ? ", instrumental" : ""}: ${instruction}`
+  };
+}
 async function withPatch(platform, project, request) {
   const { terrain, ...body } = request.body;
   const asset = await platform.web.asset(project, terrain);
@@ -6300,9 +6406,9 @@ async function shapedRequest(context, asked, args) {
   if (stringOf(args, "tiles") !== void 0) throw new CliError("--tiles is a pixel-art concept art's");
   return { kind, body, ...references.length > 0 ? { images: { references } } : {}, words };
 }
-async function confirmed(context, platform, what, prices, kind, yes) {
+async function confirmed(context, platform, what, prices, kind, yes, body) {
   const usage = usageOf$1(await platform.web.billing());
-  const share = costShareWords(prices, kind, usage);
+  const share = costShareWords(prices, kind, usage, body);
   const priced = share === null ? "using what the platform will say of your limit" : `using ${share}`;
   context.io.warn(`Making ${what}, ${priced}; ${leftWords(usage)}.
 `);
@@ -6328,7 +6434,7 @@ async function followed(context, platform, jobId) {
 const generate = {
   name: "generate",
   summary: "Generate an asset, a change of a picture, terrain, a sound or a visual effect on the platform, then pull it, keep it or write it",
-  usage: "<object|creature|concept-art|icons|ui|variant|edit|animate|pose|rotate|state|terrain|terrain-animation|sfx|speech|music|vfx> [--instruction <text>] [--source <image id>] [--state <state>] [--into <sprite> --name <name>] [--upper <ground> --lower <ground>] [--terrain <asset>] [--text <text> --voice <voice>] [--preset <preset> | --part <part>…] [--subject <image id>] [--out <path>] [--size <c>x<r>|<w>x<h>|<px>] [--transparent] [--pixel-art] [--tiles <c>x<r>] [--tag <tag>]… [--mask <png>] [--names <list>] [--purpose skill|item] [--sketch <json>] [--reference <png>]… [--no-enrich] [--yes]",
+  usage: "<object|creature|concept-art|icons|ui|variant|edit|animate|pose|rotate|state|terrain|terrain-animation|sfx|speech|music|vfx> [--instruction <text>] [--source <image id>] [--state <state>] [--into <sprite> --name <name>] [--upper <ground> --lower <ground>] [--terrain <asset>] [--text <text> --voice <voice>] [--seconds <s>] [--loop] [--instrumental] [--plan <json>] [--preset <preset> | --part <part>…] [--subject <image id>] [--out <path>] [--size <c>x<r>|<w>x<h>|<px>] [--transparent] [--pixel-art] [--tiles <c>x<r>] [--tag <tag>]… [--mask <png>] [--names <list>] [--purpose skill|item] [--sketch <json>] [--reference <png>]… [--no-enrich] [--yes]",
   options: {
     instruction: {
       type: "string",
@@ -6384,7 +6490,7 @@ const generate = {
     const platform = await signedIn(context);
     const request = asked.kind === "terrain-animation" ? await withPatch(platform, project, asked) : asked;
     const prices = await platform.web.prices();
-    const uses = await confirmed(context, platform, request.words, prices, request.kind, flagOf(args, "yes"));
+    const uses = await confirmed(context, platform, request.words, prices, request.kind, flagOf(args, "yes"), request.body);
     const jobId = await paying(platform, () => startGeneration(platform.web, project, request));
     context.io.warn(`Started the job ${jobId}.
 `);
@@ -7374,7 +7480,7 @@ function terminalOf(streams) {
     step: (title, at = "step") => drawStep(streams.stderr, title, at)
   };
 }
-const version = "0.57.1";
+const version = "0.59.0";
 const manifest = {
   version
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelvibing/cli",
-  "version": "0.57.1",
+  "version": "0.59.0",
   "description": "PixelVibing: pixel art game assets from the command line, and the Skills that teach coding assistants to make them.",
   "license": "MIT",
   "homepage": "https://pixelvibing.com",

package/skills/pixelvibing-sound/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixelvibing-sound
-description: Generate sounds for this game on PixelVibing — a sound effect such as a coin picked up or a door creaking, a line of speech in a voice, or a piece of music — with pixel-vibing-cli or the PixelVibing MCP server, written as MP3 files. Use when the game needs audio.
+description: Generate sounds for this game on PixelVibing — a sound effect such as a coin picked up or a door creaking, a line of speech in a voice, or a piece of music up to ten minutes long, from a description or section by section — with pixel-vibing-cli or the PixelVibing MCP server, written as MP3 files. Use when the game needs audio.
 ---
 
 # Sound
@@ -14,7 +14,23 @@ Load the `pixelvibing` Skill first: who is signed in, the limit.
 ```bash
 pixel-vibing-cli generate sfx --instruction "<what it sounds like>" [--seconds <s>] [--loop] [--out <file>] --yes --json
 pixel-vibing-cli generate speech --text "<what is said>" --voice <voice> [--out <file>] --yes --json
-pixel-vibing-cli generate music --instruction "<the piece>" [--out <file>] --yes --json
+pixel-vibing-cli generate music --instruction "<the piece>" [--seconds <3-600>] [--instrumental] [--out <file>] --yes --json
+pixel-vibing-cli generate music --plan <plan.json> [--out <file>] --yes --json
+```
+
+A plan's file is the track section by section, in order:
+
+```json
+{
+  "styles": ["chiptune", "heroic", "140 bpm"],
+  "avoid": ["vocals"],
+  "sections": [
+    { "name": "intro", "seconds": 15, "styles": ["soft pads"] },
+    { "name": "theme", "seconds": 90, "lyrics": ["Sail on", "the harbour waits"] },
+    { "name": "outro", "seconds": 20, "avoid": ["drums"] }
+  ],
+  "flexibleLengths": false
+}
 ```
 
 Each writes its sound as an MP3 into `pixelvibing/sounds/`, or to the file `--out` names, once
@@ -25,7 +41,8 @@ its job is done. `pixel-vibing-cli generate --help` lists the voices.
 ```json
 { "project": "<id>", "kind": "sfx", "description": "a coin picked up, bright and short", "seconds": 1, "max_percent": 30 }
 { "project": "<id>", "kind": "speech", "text": "Welcome aboard, traveller.", "voice": "<voice>", "max_percent": 30 }
-{ "project": "<id>", "kind": "music", "description": "a calm harbour theme on strings", "max_percent": 30 }
+{ "project": "<id>", "kind": "music", "description": "a calm harbour theme on strings", "seconds": 180, "instrumental": true, "max_percent": 30 }
+{ "project": "<id>", "kind": "music", "plan": { "styles": ["chiptune"], "sections": [{ "name": "intro", "seconds": 15 }, { "name": "loop", "seconds": 90 }] }, "max_percent": 30 }
 ```
 
 with the tool `generate_sound`. `get_job` follows the job and, once done, names its `sounds`;
@@ -39,7 +56,17 @@ with the tool `generate_sound`. `get_job` follows the job and, once done, names
 - **Speech.** The words exactly as they are said, in a voice. Keep a line short; one line a
   generation.
 - **Music.** The mood, the instruments and the tempo: "a calm harbour theme on strings and a
-  soft accordion".
+  soft accordion". It runs 60 seconds unless `--seconds` (`seconds`) says otherwise, from 3 to
+  600. A game's theme, a level's loop or a menu track is asked at its full length: a short one
+  ends where it stops. `--instrumental` (`instrumental`) makes one with no voice.
+- **Music section by section.** Give a plan instead of a description when the track has parts
+  that must land in order: an intro, a loop, a boss phase, an ending. Each section is 3 to 120
+  seconds, with its own styles, styles to avoid, and lyrics for its sung lines (none for an
+  instrumental part); the track is at most 600 seconds in all. `flexibleLengths`
+  (`flexible_lengths` on the MCP server) lets each section's length move while the track's stays.
+- **What music uses.** Music uses the limit by the minute of its length, rounded up: a
+  four-minute theme uses four times a one-minute one. Say so before asking for a long track, and
+  keep `max_percent` to what the person agreed.
 - **Original sound.** Never another game's music or theme, and never a real person's voice:
   when the person names one, make original sound in its spirit and say so.
 - **Where it goes.** The game loads the MP3 from where it was written; copy it into the game's