@vargai/sdk 0.1.1

package/action/edit/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: video-editing
+description: edit videos with ffmpeg operations including resize, trim, concat, social media optimization, and montage creation. use for video editing, format conversion, social media prep, merging clips, or batch video operations.
+allowed-tools: Read, Bash
+---
+
+# video editing
+
+comprehensive video editing service combining ffmpeg operations into common workflows.
+
+## commands
+
+### prepare for social media
+```bash
+bun run service/edit.ts social <input> <output> <platform> [audioPath]
+```
+
+automatically resize and optimize for platform specs:
+- **tiktok**: 1080x1920 (9:16)
+- **instagram**: 1080x1920 (9:16)
+- **youtube-shorts**: 1080x1920 (9:16)
+- **youtube**: 1920x1080 (16:9)
+- **twitter**: 1280x720 (16:9)
+
+**example:**
+```bash
+bun run service/edit.ts social raw.mp4 tiktok.mp4 tiktok
+bun run service/edit.ts social raw.mp4 ig.mp4 instagram audio.mp3
+```
+
+### create montage
+```bash
+bun run service/edit.ts montage <output> <clip1> <clip2> [clip3...]
+```
+
+combine multiple video clips into one:
+
+**example:**
+```bash
+bun run service/edit.ts montage final.mp4 intro.mp4 main.mp4 outro.mp4
+```
+
+### quick trim
+```bash
+bun run service/edit.ts trim <input> <output> <start> [end]
+```
+
+extract a segment from video:
+
+**example:**
+```bash
+bun run service/edit.ts trim long.mp4 short.mp4 10 30
+# extracts seconds 10-30
+```
+
+### quick resize
+```bash
+bun run service/edit.ts resize <input> <output> <preset>
+```
+
+resize to common aspect ratios:
+- **vertical**: 9:16 (1080x1920)
+- **square**: 1:1 (1080x1080)
+- **landscape**: 16:9 (1920x1080)
+- **4k**: 3840x2160
+
+**example:**
+```bash
+bun run service/edit.ts resize raw.mp4 vertical.mp4 vertical
+```
+
+### merge with audio
+```bash
+bun run service/edit.ts merge_audio <audio> <output> <video1> [video2...]
+```
+
+concatenate videos and add audio overlay:
+
+**example:**
+```bash
+bun run service/edit.ts merge_audio song.mp3 final.mp4 clip1.mp4 clip2.mp4
+```
+
+## as library
+
+```typescript
+import { 
+  prepareForSocial,
+  createMontage,
+  quickTrim,
+  quickResize,
+  mergeWithAudio,
+  editPipeline
+} from "./service/edit"
+
+// social media optimization
+await prepareForSocial({
+  input: "raw.mp4",
+  output: "tiktok.mp4",
+  platform: "tiktok",
+  withAudio: "audio.mp3"
+})
+
+// create montage
+await createMontage({
+  clips: ["clip1.mp4", "clip2.mp4"],
+  output: "montage.mp4",
+  maxClipDuration: 5,
+  targetResolution: { width: 1920, height: 1080 }
+})
+
+// trim video
+await quickTrim("video.mp4", "trimmed.mp4", 10, 30)
+
+// resize video
+await quickResize("video.mp4", "resized.mp4", "vertical")
+
+// merge videos with audio
+await mergeWithAudio(
+  ["clip1.mp4", "clip2.mp4"],
+  "audio.mp3",
+  "final.mp4"
+)
+```
+
+## advanced: edit pipeline
+
+chain multiple operations:
+
+```typescript
+import { editPipeline } from "./service/edit"
+
+await editPipeline({
+  steps: [
+    {
+      operation: "resize",
+      options: {
+        input: "raw.mp4",
+        width: 1080,
+        height: 1920
+      }
+    },
+    {
+      operation: "add_audio",
+      options: {
+        videoPath: "temp.mp4",
+        audioPath: "music.mp3"
+      }
+    },
+    {
+      operation: "trim",
+      options: {
+        input: "temp2.mp4",
+        start: 0,
+        duration: 30
+      }
+    }
+  ],
+  finalOutput: "final.mp4"
+})
+```
+
+**available operations:**
+- `concat` - concatenate videos
+- `add_audio` - overlay audio
+- `resize` - change dimensions
+- `trim` - extract segment
+- `convert` - change format
+- `extract_audio` - extract audio track
+
+## when to use
+
+use this skill when:
+- preparing videos for social media platforms
+- combining multiple video clips
+- extracting segments from longer videos
+- resizing to specific aspect ratios
+- adding background music to video montages
+- batch processing video files
+- optimizing videos for specific platforms
+
+## typical workflows
+
+### social media content
+1. create or edit raw video
+2. add captions (captions service)
+3. prepare for platform (this service)
+4. upload
+
+### video montage
+1. collect multiple clips
+2. create montage (this service)
+3. add audio overlay (this service)
+4. add captions if needed (captions service)
+
+### talking character for social
+1. generate character (image service)
+2. animate (video service)
+3. sync with voice (sync service)
+4. add captions (captions service)
+5. optimize for tiktok/instagram (this service)
+
+## tips
+
+**social media optimization:**
+- use platform-specific presets for correct aspect ratio
+- vertical format (9:16) works for tiktok, instagram reels, youtube shorts
+- landscape (16:9) works for youtube, twitter
+
+**montage creation:**
+- all clips should have similar resolution for best results
+- use `maxClipDuration` to keep montage paced
+- `targetResolution` ensures consistent quality
+
+**trimming:**
+- start time is in seconds
+- end time is optional (omit to trim to end of video)
+- use for extracting highlights or removing unwanted sections
+
+## environment variables
+
+no api keys required - uses ffmpeg
+
+**system requirements:**
+- ffmpeg must be installed
+- `brew install ffmpeg` (macos)
+- `apt-get install ffmpeg` (linux)
+
+## processing time
+
+depends on operation and video size:
+- trim: 5-10 seconds
+- resize: 10-30 seconds
+- concat: 10-30 seconds per clip
+- social optimization: 15-45 seconds

package/action/edit/index.ts

@@ -0,0 +1,437 @@
+#!/usr/bin/env bun
+
+/**
+ * video editing service
+ * combines multiple ffmpeg operations into common workflows
+ */
+
+import { existsSync } from "node:fs";
+import { extname } from "node:path";
+import type { ActionMeta } from "../../cli/types";
+import {
+  type AddAudioOptions,
+  addAudio,
+  type ConcatVideosOptions,
+  type ConvertFormatOptions,
+  concatVideos,
+  convertFormat,
+  extractAudio,
+  type ResizeVideoOptions,
+  resizeVideo,
+  type TrimVideoOptions,
+  trimVideo,
+} from "../../lib/ffmpeg";
+
+export const meta: ActionMeta = {
+  name: "edit",
+  type: "action",
+  description: "trim/resize video",
+  inputType: "video",
+  outputType: "video",
+  schema: {
+    input: {
+      type: "object",
+      required: ["input", "output"],
+      properties: {
+        input: {
+          type: "string",
+          format: "file-path",
+          description: "input video file",
+        },
+        output: {
+          type: "string",
+          format: "file-path",
+          description: "output video path",
+        },
+        start: {
+          type: "number",
+          description: "start time in seconds (for trim)",
+        },
+        duration: {
+          type: "number",
+          description: "duration in seconds (for trim)",
+        },
+        preset: {
+          type: "string",
+          enum: ["vertical", "square", "landscape", "4k"],
+          description: "resize preset",
+        },
+      },
+    },
+    output: { type: "string", format: "file-path", description: "video path" },
+  },
+  async run(options) {
+    const { input, output, start, duration, preset } = options as {
+      input: string;
+      output: string;
+      start?: number;
+      duration?: number;
+      preset?: "vertical" | "square" | "landscape" | "4k";
+    };
+    if (preset) {
+      return quickResize(input, output, preset);
+    }
+    if (start !== undefined) {
+      return quickTrim(
+        input,
+        output,
+        start,
+        duration ? start + duration : undefined,
+      );
+    }
+    throw new Error("specify --start for trim or --preset for resize");
+  },
+};
+
+// types
+export interface EditPipelineStep {
+  operation:
+    | "concat"
+    | "add_audio"
+    | "resize"
+    | "trim"
+    | "convert"
+    | "extract_audio";
+  // options should contain all parameters except 'output' which is added by the pipeline
+  // biome-ignore lint/suspicious/noExplicitAny: pipeline options are validated at runtime by underlying ffmpeg functions
+  options: Record<string, any>;
+}
+
+export interface EditPipelineOptions {
+  steps: EditPipelineStep[];
+  finalOutput: string;
+}
+
+export interface PrepareForSocialOptions {
+  input: string;
+  output: string;
+  platform: "tiktok" | "instagram" | "youtube-shorts" | "youtube" | "twitter";
+  withAudio?: string;
+}
+
+export interface CreateMontageOptions {
+  clips: string[];
+  output: string;
+  maxClipDuration?: number;
+  targetResolution?: { width: number; height: number };
+}
+
+// core functions
+
+/**
+ * run a series of editing operations in sequence
+ * each step uses output from previous step as input
+ */
+export async function editPipeline(
+  options: EditPipelineOptions,
+): Promise<string> {
+  const { steps, finalOutput } = options;
+
+  if (!steps || steps.length === 0) {
+    throw new Error("at least one step is required");
+  }
+
+  console.log(`[edit] running ${steps.length} editing steps...`);
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (!step) {
+      throw new Error(`step ${i} is undefined`);
+    }
+
+    const isLastStep = i === steps.length - 1;
+    const output = isLastStep
+      ? finalOutput
+      : `/tmp/edit-step-${i}${extname(finalOutput)}`;
+
+    console.log(`[edit] step ${i + 1}/${steps.length}: ${step.operation}`);
+
+    switch (step.operation) {
+      case "concat":
+        await concatVideos({
+          ...step.options,
+          output,
+        } as ConcatVideosOptions);
+        break;
+
+      case "add_audio":
+        await addAudio({
+          ...step.options,
+          output,
+        } as AddAudioOptions);
+        break;
+
+      case "resize":
+        await resizeVideo({
+          ...step.options,
+          output,
+        } as ResizeVideoOptions);
+        break;
+
+      case "trim":
+        await trimVideo({
+          ...step.options,
+          output,
+        } as TrimVideoOptions);
+        break;
+
+      case "convert":
+        await convertFormat({
+          ...step.options,
+          output,
+        } as ConvertFormatOptions);
+        break;
+
+      case "extract_audio":
+        await extractAudio((step.options as { input: string }).input, output);
+        break;
+
+      default:
+        throw new Error(`unknown operation: ${step.operation}`);
+    }
+  }
+
+  console.log(`[edit] pipeline complete: ${finalOutput}`);
+  return finalOutput;
+}
+
+/**
+ * prepare video for social media platform
+ * automatically sets correct aspect ratio and resolution
+ */
+export async function prepareForSocial(
+  options: PrepareForSocialOptions,
+): Promise<string> {
+  const { input, output, platform, withAudio } = options;
+
+  if (!input || !output || !platform) {
+    throw new Error("input, output, and platform are required");
+  }
+
+  if (!existsSync(input)) {
+    throw new Error(`input file not found: ${input}`);
+  }
+
+  console.log(`[edit] preparing video for ${platform}...`);
+
+  const platformSpecs: Record<
+    string,
+    { width: number; height: number; aspectRatio: string }
+  > = {
+    tiktok: { width: 1080, height: 1920, aspectRatio: "9:16" },
+    instagram: { width: 1080, height: 1920, aspectRatio: "9:16" },
+    "youtube-shorts": { width: 1080, height: 1920, aspectRatio: "9:16" },
+    youtube: { width: 1920, height: 1080, aspectRatio: "16:9" },
+    twitter: { width: 1280, height: 720, aspectRatio: "16:9" },
+  };
+
+  const spec = platformSpecs[platform];
+  if (!spec) {
+    throw new Error(`unknown platform: ${platform}`);
+  }
+
+  const steps: EditPipelineStep[] = [];
+
+  // resize to platform specs
+  steps.push({
+    operation: "resize",
+    options: {
+      input,
+      width: spec.width,
+      height: spec.height,
+    },
+  });
+
+  // add audio if provided
+  if (withAudio) {
+    if (!existsSync(withAudio)) {
+      throw new Error(`audio file not found: ${withAudio}`);
+    }
+    steps.push({
+      operation: "add_audio",
+      options: {
+        videoPath: input,
+        audioPath: withAudio,
+      },
+    });
+  }
+
+  return editPipeline({ steps, finalOutput: output });
+}
+
+/**
+ * create a montage from multiple video clips
+ * optionally trim clips and resize to consistent resolution
+ */
+export async function createMontage(
+  options: CreateMontageOptions,
+): Promise<string> {
+  const { clips, output, maxClipDuration, targetResolution } = options;
+
+  if (!clips || clips.length === 0) {
+    throw new Error("at least one clip is required");
+  }
+  if (!output) {
+    throw new Error("output is required");
+  }
+
+  console.log(`[edit] creating montage from ${clips.length} clips...`);
+
+  // validate all clips exist
+  for (const clip of clips) {
+    if (!existsSync(clip)) {
+      throw new Error(`clip not found: ${clip}`);
+    }
+  }
+
+  let processedClips = clips;
+
+  // trim clips if max duration specified
+  if (maxClipDuration) {
+    console.log(`[edit] trimming clips to ${maxClipDuration}s...`);
+    processedClips = [];
+
+    for (let i = 0; i < clips.length; i++) {
+      const clip = clips[i];
+      if (!clip) {
+        throw new Error(`clip ${i} is undefined`);
+      }
+      const trimmedPath = `/tmp/montage-clip-${i}${extname(clip)}`;
+      await trimVideo({
+        input: clip,
+        output: trimmedPath,
+        start: 0,
+        duration: maxClipDuration,
+      });
+      processedClips.push(trimmedPath);
+    }
+  }
+
+  // resize clips if target resolution specified
+  if (targetResolution) {
+    console.log(
+      `[edit] resizing clips to ${targetResolution.width}x${targetResolution.height}...`,
+    );
+    const resizedClips = [];
+
+    for (let i = 0; i < processedClips.length; i++) {
+      const clip = processedClips[i];
+      if (!clip) {
+        throw new Error(`clip ${i} is undefined`);
+      }
+      const resizedPath = `/tmp/montage-resized-${i}${extname(clip)}`;
+      await resizeVideo({
+        input: clip,
+        output: resizedPath,
+        width: targetResolution.width,
+        height: targetResolution.height,
+      });
+      resizedClips.push(resizedPath);
+    }
+
+    processedClips = resizedClips;
+  }
+
+  // concatenate all clips
+  return concatVideos({
+    inputs: processedClips,
+    output,
+  });
+}
+
+/**
+ * quick trim: trim video to specific segment
+ */
+export async function quickTrim(
+  input: string,
+  output: string,
+  start: number,
+  end?: number,
+): Promise<string> {
+  if (!input || !output) {
+    throw new Error("input and output are required");
+  }
+
+  const duration = end ? end - start : undefined;
+
+  console.log(
+    `[edit] trimming video from ${start}s${duration ? ` for ${duration}s` : ""}...`,
+  );
+
+  return trimVideo({ input, output, start, duration });
+}
+
+/**
+ * quick resize: resize video to common aspect ratios
+ */
+export async function quickResize(
+  input: string,
+  output: string,
+  preset: "vertical" | "square" | "landscape" | "4k",
+): Promise<string> {
+  if (!input || !output) {
+    throw new Error("input and output are required");
+  }
+
+  const presets: Record<
+    string,
+    { width: number; height: number; label: string }
+  > = {
+    vertical: { width: 1080, height: 1920, label: "9:16 (1080x1920)" },
+    square: { width: 1080, height: 1080, label: "1:1 (1080x1080)" },
+    landscape: { width: 1920, height: 1080, label: "16:9 (1920x1080)" },
+    "4k": { width: 3840, height: 2160, label: "4K (3840x2160)" },
+  };
+
+  const spec = presets[preset];
+  if (!spec) {
+    throw new Error(`unknown preset: ${preset}`);
+  }
+
+  console.log(`[edit] resizing to ${spec.label}...`);
+
+  return resizeVideo({
+    input,
+    output,
+    width: spec.width,
+    height: spec.height,
+  });
+}
+
+/**
+ * merge multiple videos with optional audio overlay
+ */
+export async function mergeWithAudio(
+  videos: string[],
+  audio: string,
+  output: string,
+): Promise<string> {
+  if (!videos || videos.length === 0) {
+    throw new Error("at least one video is required");
+  }
+  if (!audio || !output) {
+    throw new Error("audio and output are required");
+  }
+
+  console.log(`[edit] merging ${videos.length} videos with audio...`);
+
+  // first concatenate videos
+  const tempVideo = `/tmp/merged-video${extname(output)}`;
+  await concatVideos({
+    inputs: videos,
+    output: tempVideo,
+  });
+
+  // then add audio
+  return addAudio({
+    videoPath: tempVideo,
+    audioPath: audio,
+    output,
+  });
+}
+
+// cli
+if (import.meta.main) {
+  const { runCli } = await import("../../cli/runner");
+  runCli(meta);
+}