@jclvsh/dropspace 2.51.0 → 2.52.0

package/README.md

@@ -62,7 +62,7 @@ dropspace launches --help
 | autopilot              | status, configure, review, approve, reject, run, runs                                                                                                                                                                  |
 | recommendations (recs) | list, apply, dismiss                                                                                                                                                                                                   |
 | songs                  | list, get, add, lyrics, rename, retry, delete                                                                                                                                                                          |
-| song-reels             | make, list, get, retry, launch, delete                                                                                                                                                                                 |
+| song-reels             | make, rollout, list, get, retry, launch, keep, delete                                                                                                                                                                               |
 | scene-clips            | cut, list, get, retry, delete                                                                                                                                                                                          |
 | profile                | get, update                                                                                                                                                                                                            |
 | billing                | portal                                                                                                                                                                                                                 |
@@ -397,10 +397,12 @@ Reddit engagement (drafted comments in other communities) is paused: its tools a
 | `add_song` | Add a song from a YouTube or SoundCloud link, or a public audio file url (local package only) |
 | `get_song_lyrics` | The song's lyrics with word timings, transcribed once (local package only) |
 | `delete_song` | Delete a song and its audio file (local package only) |
-| `make_song_reel` | Make a 9:16 lyric reel from a snippet of a song: clips from the media library or a gradient, lyrics burned in (local package only) |
+| `make_song_reel` | Make a 9:16 lyric reel from a snippet of a song: clips from the media library, a gradient, or AI b-roll, lyrics and a hook line burned in (local package only) |
+| `rollout_song_reels` | Make 2-10 versions of one reel at once (style, then clip order or background, changing per version) (local package only) |
+| `keep_song_reel` | Keep one version of a rollout; the others are deleted with their library items (local package only) |
 | `list_song_reels` | Lyric reels, newest first, with render status and video_url once ready (local package only) |
 | `get_song_reel` | One reel with its lyric lines (local package only) |
-| `launch_song_reel` | A draft launch carrying a ready reel and its lyrics as the caption (local package only) |
+| `launch_song_reel` | A draft launch carrying a ready reel and its hook and lyrics as the caption; `trial_reel` makes it an Instagram trial reel (local package only) |
 | `delete_song_reel` | Delete a reel; its media library item and launch stay (local package only) |
 | `cut_scene_clips` | Cut a long video (a media library video, a YouTube link, or a public video url) into 2-8 second clips at its scene changes, up to 40, into the media library (local package only) |
 | `list_scene_clip_jobs` | Clip jobs, newest first, with status, clips made and added, and each clip's urls (local package only) |

package/dist/commands/song-reels.js

@@ -1,4 +1,29 @@
 import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+/** The reel body shared by `make` and `rollout`. */
+function reelBody(opts) {
+    const ai = opts.ai !== undefined && opts.ai !== false;
+    const body = {
+        snippet_start: Number(opts.start),
+        snippet_end: Number(opts.end),
+        style: opts.style,
+        footage_mode: ai ? "ai" : opts.clips ? "clips" : "none",
+    };
+    if (opts.clips && !ai)
+        body.clip_ids = String(opts.clips)
+            .split(",")
+            .map((id) => id.trim())
+            .filter(Boolean);
+    if (opts.background)
+        body.background = opts.background;
+    if (opts.hook)
+        body.hook_text = String(opts.hook);
+    if (ai) {
+        if (typeof opts.ai === "string" && opts.ai.trim())
+            body.ai_prompt = opts.ai.trim();
+        body.ai_clips = Number(opts.aiClips ?? 2);
+    }
+    return body;
+}
 export function registerSongReelCommands(program, client) {
     const reels = program.command("song-reels").description("lyric reels made from your songs (pro and premium)");
     reels
@@ -9,19 +34,39 @@ export function registerSongReelCommands(program, client) {
         .option("--style <style>", "lower-third, center-bold, karaoke, one-word, or caps-top", "lower-third")
         .option("--clips <ids>", "media library ids in order, comma separated (footage from your library)")
         .option("--background <name>", "midnight, sunset, forest, sand, slate, or violet (no footage)")
+        .option("--hook <text>", "a line burned in for the whole snippet, up to 90 characters")
+        .option("--ai [prompt]", "AI b-roll instead of clips: what it should show (the lyrics stand in when empty); each clip is one of your plan's AI videos")
+        .option("--ai-clips <n>", "b-roll clips to generate, 1-4 (with --ai)", "2")
+        .action(async (songId, opts) => {
+        try {
+            formatOutput(await client.post(`/songs/${songId}/reels`, reelBody(opts)), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    reels
+        .command("rollout <songId>")
+        .description("make N versions of one reel at once (the style, then the clip order or background, changes per version)")
+        .requiredOption("--count <n>", "how many versions, 2-10")
+        .requiredOption("--start <seconds>", "snippet start, seconds from the song's start")
+        .requiredOption("--end <seconds>", "snippet end, 5 to 30 seconds after the start")
+        .option("--style <style>", "the first style (the versions cycle through --styles)", "lower-third")
+        .option("--styles <styles>", "the styles to cycle through, comma separated; all five when omitted")
+        .option("--clips <ids>", "media library ids in order, comma separated (footage from your library)")
+        .option("--background <name>", "midnight, sunset, forest, sand, slate, or violet (no footage)")
+        .option("--hook <text>", "a line burned in for the whole snippet, up to 90 characters")
+        .option("--ai [prompt]", "AI b-roll, generated once and shared by every version")
+        .option("--ai-clips <n>", "b-roll clips to generate, 1-4 (with --ai)", "2")
         .action(async (songId, opts) => {
         try {
-            const body = {
-                snippet_start: Number(opts.start),
-                snippet_end: Number(opts.end),
-                style: opts.style,
-                footage_mode: opts.clips ? "clips" : "none",
-            };
-            if (opts.clips)
-                body.clip_ids = String(opts.clips).split(",").map((id) => id.trim()).filter(Boolean);
-            if (opts.background)
-                body.background = opts.background;
-            formatOutput(await client.post(`/songs/${songId}/reels`, body), getFormat(program.opts()));
+            const body = { ...reelBody(opts), count: Number(opts.count) };
+            if (opts.styles)
+                body.styles = String(opts.styles)
+                    .split(",")
+                    .map((style) => style.trim())
+                    .filter(Boolean);
+            formatOutput(await client.post(`/songs/${songId}/reels/rollout`, body), getFormat(program.opts()));
         }
         catch (error) {
             handleError(error);
@@ -31,6 +76,7 @@ export function registerSongReelCommands(program, client) {
         .command("list")
         .description("your lyric reels, newest first")
         .option("--song <id>", "only this song's reels")
+        .option("--rollout <id>", "only this rollout's versions")
         .option("--page <n>", "page number")
         .option("--page-size <n>", "reels per page (max 100)")
         .action(async (opts) => {
@@ -38,6 +84,8 @@ export function registerSongReelCommands(program, client) {
             const params = {};
             if (opts.song)
                 params.song_id = opts.song;
+            if (opts.rollout)
+                params.rollout_id = opts.rollout;
             if (opts.page)
                 params.page = opts.page;
             if (opts.pageSize)
@@ -73,9 +121,21 @@ export function registerSongReelCommands(program, client) {
     reels
         .command("launch <id>")
         .description("make a draft launch from a ready reel")
+        .option("--trial", "post it as an Instagram trial reel (shown to non-followers first)")
+        .action(async (id, opts) => {
+        try {
+            formatOutput(await client.post(`/song-reels/${id}/launch`, opts.trial ? { trial_reel: true } : {}), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    reels
+        .command("keep <id>")
+        .description("keep this version of a rollout; its other versions are deleted (one with a launch stays)")
         .action(async (id) => {
         try {
-            formatOutput(await client.post(`/song-reels/${id}/launch`), getFormat(program.opts()));
+            formatOutput(await client.post(`/song-reels/${id}/keep`), getFormat(program.opts()));
         }
         catch (error) {
             handleError(error);

package/dist/tool-policy.js

@@ -148,6 +148,8 @@ const FULL_TOOL_POLICY = {
     get_song_reel: localOnly("media", "read"),
     launch_song_reel: localOnly("media", "write"),
     delete_song_reel: localOnly("media", "write"),
+    rollout_song_reels: localOnly("media", "write"),
+    keep_song_reel: localOnly("media", "write"),
     // scene clips: a job spends server minutes and adds up to 40 items to the media library
     cut_scene_clips: localOnly("media", "write"),
     list_scene_clip_jobs: localOnly("media", "read"),

package/dist/tools/song-reels.js

@@ -10,17 +10,42 @@ function fail(error) {
 }
 const STYLES = ["lower-third", "center-bold", "karaoke", "one-word", "caps-top"];
 const BACKGROUNDS = ["midnight", "sunset", "forest", "sand", "slate", "violet"];
+const REEL_INPUT = {
+    song_id: z.string().uuid(),
+    snippet_start: z.number().min(0).describe("seconds from the start of the song"),
+    snippet_end: z.number().positive().describe("5 to 30 seconds after snippet_start"),
+    style: z
+        .enum(STYLES)
+        .describe("how the lyrics look: lower-third, center-bold, karaoke (word by word), one-word, caps-top"),
+    footage_mode: z.enum(["clips", "none", "ai"]),
+    clip_ids: z
+        .array(z.string().uuid())
+        .max(20)
+        .optional()
+        .describe("media library ids, in order (footage_mode clips)"),
+    background: z.enum(BACKGROUNDS).optional().describe("the gradient (footage_mode none); midnight unless given"),
+    hook_text: z
+        .string()
+        .min(1)
+        .max(90)
+        .optional()
+        .describe("a line burned in for the whole snippet (top; low under caps-top); it also opens the launch caption"),
+    ai_prompt: z
+        .string()
+        .max(500)
+        .optional()
+        .describe("what the b-roll should show (footage_mode ai); the lyrics stand in when empty"),
+    ai_clips: z
+        .number()
+        .int()
+        .min(1)
+        .max(4)
+        .optional()
+        .describe("b-roll clips to generate, 1-4 (footage_mode ai); 2 unless given"),
+};
 /** Lyric reels made from songs (pro and premium). Local package only. */
 export function registerSongReelTools(server, client) {
-    server.tool("make_song_reel", "make a 9:16 lyric reel from a snippet of a ready song (get_song for its duration and peaks): 5 to 30 seconds of the song under footage, with the lyrics inside the snippet burned in. footage_mode clips uses the user's media library videos and images (clip_ids from list_media_library, in order; the clip changes at lyric lines, skipping cuts closer than 1.5 s apart); none puts the lyrics over a gradient (background). the lyrics are read from the song on the first reel (takes up to a minute). the render runs on the server: the reel comes back pending; read it with get_song_reel until ready (video_url, and it is in the media library) or failed. counts against the plan's song reels per billing period (pro 30, premium 100; a rendered reel keeps its slot even when deleted).", {
-        song_id: z.string().uuid(),
-        snippet_start: z.number().min(0).describe("seconds from the start of the song"),
-        snippet_end: z.number().positive().describe("5 to 30 seconds after snippet_start"),
-        style: z.enum(STYLES).describe("how the lyrics look: lower-third, center-bold, karaoke (word by word), one-word, caps-top"),
-        footage_mode: z.enum(["clips", "none"]),
-        clip_ids: z.array(z.string().uuid()).max(20).optional().describe("media library ids, in order (footage_mode clips)"),
-        background: z.enum(BACKGROUNDS).optional().describe("the gradient (footage_mode none); midnight unless given"),
-    }, async ({ song_id, ...body }) => {
+    server.tool("make_song_reel", "make a 9:16 lyric reel from a snippet of a ready song (get_song for its duration and peaks): 5 to 30 seconds of the song under footage, with the lyrics inside the snippet burned in and, if given, a hook line held across the whole snippet. footage_mode clips uses the user's media library videos and images (clip_ids from list_media_library, in order; the clip changes at lyric lines, skipping cuts closer than 1.5 s apart); none puts the lyrics over a gradient (background); ai generates b-roll from ai_prompt (ai_clips veo clips of 8 s, each one of the plan's AI videos at $1.20; the reel renders once they land, footage_status generating until then). the lyrics are read from the song on the first reel (takes up to a minute). the render runs on the server: the reel comes back pending; read it with get_song_reel until ready (video_url, and it is in the media library) or failed. counts against the plan's song reels per billing period (pro 30, premium 100; a rendered reel keeps its slot even when deleted).", REEL_INPUT, async ({ song_id, ...body }) => {
         try {
             return text(await client.post(`/songs/${song_id}/reels`, body));
         }
@@ -28,15 +53,35 @@ export function registerSongReelTools(server, client) {
             return fail(error);
         }
     });
-    server.tool("list_song_reels", "the user's lyric reels, newest first: id, song_id, title, snippet, style, footage_mode, render_status (pending, running, ready, or failed with render_error), video_url and thumbnail_url once ready, media_library_id, launch_id. song_id narrows to one song.", {
+    server.tool("rollout_song_reels", "make count (2-10) versions of one reel at once, as one rollout: the same snippet, lines, and footage, the style and then the clip order (or background) changing per version, never two the same. every version is a reel of its own (rollout_id, variant_index, variant_note) that counts against the plan's song reels; when fewer slots are left than count, nothing is made and the error says how many are left. the versions render in turn. then keep_song_reel keeps the best, or launch_song_reel each one (trial_reel true for Instagram trial reels). an ai rollout generates its b-roll once and shares it.", {
+        ...REEL_INPUT,
+        count: z.number().int().min(2).max(10).describe("how many versions"),
+        styles: z
+            .array(z.enum(STYLES))
+            .min(1)
+            .max(5)
+            .optional()
+            .describe("the styles the versions cycle through; all five when omitted"),
+    }, async ({ song_id, ...body }) => {
+        try {
+            return text(await client.post(`/songs/${song_id}/reels/rollout`, body));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("list_song_reels", "the user's lyric reels, newest first: id, song_id, title, snippet, style, footage_mode, hook_text, rollout_id / variant_index / variant_note (a rollout's versions), footage_status (ai b-roll: generating, ready, failed), render_status (pending, running, ready, or failed with render_error), video_url and thumbnail_url once ready, media_library_id, launch_id. song_id narrows to one song, rollout_id to one rollout's versions.", {
         song_id: z.string().uuid().optional(),
+        rollout_id: z.string().uuid().optional(),
         page: z.number().int().min(1).optional(),
         page_size: z.number().int().min(1).max(100).optional(),
-    }, async ({ song_id, page, page_size }) => {
+    }, async ({ song_id, rollout_id, page, page_size }) => {
         try {
             const params = {};
             if (song_id)
                 params.song_id = song_id;
+            if (rollout_id)
+                params.rollout_id = rollout_id;
             if (page)
                 params.page = String(page);
             if (page_size)
@@ -55,9 +100,17 @@ export function registerSongReelTools(server, client) {
             return fail(error);
         }
     });
-    server.tool("launch_song_reel", "make a draft launch from a ready reel: the reel is its video and the snippet's lyrics its instagram caption. the launch stays a draft until the user (or update_launch + publish) sets platforms, caption, and timing, and it counts as one of the plan's launches. returns the reel with launch_id.", { reel_id: z.string().uuid() }, async ({ reel_id }) => {
+    server.tool("launch_song_reel", "make a draft launch from a ready reel: the reel is its video and the hook line plus the snippet's lyrics its instagram caption. trial_reel true makes it an Instagram trial reel (shown to non-followers first; refused with the reason when the account is not a professional account with 200 or more followers). the launch stays a draft until the user (or update_launch + publish) sets platforms, caption, and timing, and it counts as one of the plan's launches. returns the reel with launch_id.", { reel_id: z.string().uuid(), trial_reel: z.boolean().optional() }, async ({ reel_id, trial_reel }) => {
+        try {
+            return text(await client.post(`/song-reels/${reel_id}/launch`, trial_reel ? { trial_reel: true } : {}));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("keep_song_reel", "keep this version of a rollout: the rollout's other versions are deleted with their media library items and files (a version that already has a launch stays). returns the kept reel.", { reel_id: z.string().uuid() }, async ({ reel_id }) => {
         try {
-            return text(await client.post(`/song-reels/${reel_id}/launch`));
+            return text(await client.post(`/song-reels/${reel_id}/keep`));
         }
         catch (error) {
             return fail(error);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/dropspace",
-	"version": "2.51.0",
+	"version": "2.52.0",
 	"description": "MCP server and CLI for the Dropspace API",
 	"repository": {
 		"type": "git",