gupsammy avatar

claude-content

Content creation skills: image generation, video compression, conversion, GIF creation, social media formatting, and audio extraction

version
0.4.18
GitHub stars
276

Install

/plugin install claude-content@Claudest

Run it inside Claude Code after adding the marketplace with /plugin marketplace add gupsammy/Claudest.

Contents

Discovered from source

Skills 7

Video Compress

Compress a video using quality-based (CRF) or size-based (2-pass) encoding.

Process

1. Obtain input file

If the user did not provide a file path, ask for it with AskUserQuestion before proceeding.

2. Probe the source

ffprobe -v quiet -print_format json -show_streams -show_format "$INPUT"

Extract: duration (seconds), file size (bytes), existing video codec, audio bitrate. If ffprobe fails (file not found, not a valid video), report the error and stop — do not attempt encoding.

3. Determine mode from user intent

  • CRF mode (quality-based): user says "without losing quality", "good quality", "make it smaller", or gives no size target
  • 2-pass mode (size-based): user specifies a target ("under 50MB", "around 20MB", "fit on X")

4. Choose codec

H.264 is the safe default: universally device-compatible and fast to encode. Use H.265 only when the size reduction justifies the slower encode time and narrower device support.

  • H.265 / libx265: target is ≤50% of original size, or user asks for "maximum compression" / "HEVC"
  • H.264 / libx264: otherwise — faster encode, wider device compatibility, safe default

5. Construct command

CRF mode:

ffmpeg -i "$INPUT" -c:v libx264 -crf 23 -c:a copy -movflags +faststart "$OUTPUT"
# CRF scale: 18=near-lossless, 23=default quality, 28=aggressive (visible loss)
# -movflags +faststart moves moov atom to front — enables progressive web playback

2-pass mode — calculate video bitrate first:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/compress-video/scripts/calc_bitrate.py "$INPUT" --target-mb "$TARGET_MB"
# Outputs: VIDEO_BITRATE_KBPS (integer)
# Formula: (target_mb * 8192 / duration_s) - audio_bitrate_kbps
# Typical audio budget: 128 kbps
# Exit 1 = target too small (bitrate would go negative); report the error and ask for a larger target before retrying.

# Pass 1 — video analysis only, no output file:
ffmpeg -y -i "$INPUT" -c:v libx264 -b:v ${VIDEO_BITRATE_KBPS}k -pass 1 -an -f null /dev/null

# Pass 2 — final encode with audio:
ffmpeg -i "$INPUT" -c:v libx264 -b:v ${VIDEO_BITRATE_KBPS}k -pass 2 \
  -c:a aac -b:a 128k -movflags +faststart "$OUTPUT"

6. Confirm with user

Show: input file size, chosen codec, mode (CRF value or calculated bitrate), output path. Wait for approval before running.

7. Run and report

After completion: input size → output size, compression ratio (e.g., "73.2 MB → 18.4 MB, 75% reduction").

Key Decisions

  • In CRF mode, use -c:a copy to preserve audio losslessly. In 2-pass mode, audio must be re-encoded (AAC 128k) because pass 1 is video-only — no audio stream is processed.
  • If input is already H.264 and the user only wants to trim or remux, recommend convert-video with -c copy instead — instant and lossless.
  • For H.265 output, substitute libx265 and add -tag:v hvc1 for Apple device compatibility.
  • Clean up ffmpeg2pass-0.log and ffmpeg2pass-0.log.mbtree after 2-pass encoding completes.

Video Convert

Identify the operation type first, then apply the matching pattern below. For multi-operation requests (e.g., trim + resize + convert), chain all filters in a single ffmpeg invocation — avoid intermediate files.

Process

  1. Identify the operation(s) from the user's request.
  2. Probe codec when converting formats; probe dimensions when resizing. Speed, rotation, flip, and frame extraction do not require probing.
  3. Construct the command using the appropriate pattern.
  4. Confirm with the user before running.
  5. Run and report output file path and size.

Operation Patterns

Format Conversion

Probe codec first — determines whether -c copy is safe:

ffprobe -v quiet -show_streams "$INPUT" | grep codec_name
# Remux: same codec, different container (e.g., H.264 MKV → MP4) — instant, lossless:
ffmpeg -i input.mkv -c copy output.mp4

# Re-encode: different codec required:
ffmpeg -i input.avi -c:v libx264 -crf 23 -c:a aac -b:a 128k output.mp4

Trimming

# Fast trim without re-encoding (-ss before -i = container-level seek):
ffmpeg -ss 00:01:30 -to 00:03:45 -i "$INPUT" -c copy "$OUTPUT"

# Re-encoding trim (use when -c copy causes A/V sync issues near keyframes):
ffmpeg -ss 00:01:30 -to 00:03:45 -i "$INPUT" -c:v libx264 -crf 23 -c:a copy "$OUTPUT"

Always try -c copy first. Fall back to re-encoding only if the user reports sync issues or the cut must land on a non-keyframe boundary.

Speed Change

# 2x speed:
ffmpeg -i "$INPUT" -filter:v "setpts=0.5*PTS" -filter:a "atempo=2.0" "$OUTPUT"

# 0.5x slow-motion:
ffmpeg -i "$INPUT" -filter:v "setpts=2.0*PTS" -filter:a "atempo=0.5" "$OUTPUT"

setpts factor = 1 / speed_multiplier. atempo range is 0.5–2.0 — chain for higher multiples: atempo=2.0,atempo=2.0 achieves 4x. For silent video, omit -filter:a entirely.

Resize / Scale

Probe dimensions first: ffprobe -v quiet -show_streams "$INPUT" | grep -E "width|height"

# Scale to width, auto height (-2 ensures H.264-compatible even height):
ffmpeg -i "$INPUT" -vf "scale=1280:-2" -c:a copy "$OUTPUT"

# Fit within bounding box without upscaling:
ffmpeg -i "$INPUT" \
  -vf "scale='min(1280,iw)':'min(720,ih)':force_original_aspect_ratio=decrease,pad=ceil(iw/2)*2:ceil(ih/2)*2" \
  -c:a copy "$OUTPUT"

Rotation / Flip

# 90° clockwise:         ffmpeg -i "$INPUT" -vf "transpose=1" "$OUTPUT"
# 90° counter-clockwise: ffmpeg -i "$INPUT" -vf "transpose=2" "$OUTPUT"
# 180°:                  ffmpeg -i "$INPUT" -vf "transpose=1,transpose=1" "$OUTPUT"
# Horizontal flip:       ffmpeg -i "$INPUT" -vf "hflip" "$OUTPUT"
# Vertical flip:         ffmpeg -i "$INPUT" -vf "vflip" "$OUTPUT"

Frame Extraction

# Single frame at timestamp:
ffmpeg -ss 00:00:10 -i "$INPUT" -frames:v 1 -q:v 2 output.jpg

# One frame every N seconds:
ffmpeg -i "$INPUT" -vf "fps=1/$N" -q:v 2 frames/frame_%04d.jpg

-q:v 2 is near-maximum JPEG quality. Use -q:v 1 for the highest quality setting.

Key Decisions

  • Never upscale — add force_original_aspect_ratio=decrease when fitting to a bounding box.
  • For multi-filter operations, chain with commas in a single -vf; but -filter:v and -filter:a must remain separate flags.
  • Use -c:a copy in all re-encode operations unless the audio format itself needs to change.
  • If ffprobe reveals a rotate metadata tag on the stream, use -vf "transpose=..." to bake rotation into pixels — -c copy preserves the metadata flag without rotating the actual frame data, which confuses many players.

Format Decision Tree

User wantsFormatFlagsWhy
Music, archive qualityFLAC-c:a flacLossless, no quality loss
Music, small + transparentMP3 VBR-c:a libmp3lame -q:a 0~200kbps avg, perceptually lossless
Podcast / voiceMP3 128k CBR-c:a libmp3lame -b:a 128kSufficient for speech, universally compatible
Mobile / streamingAAC 192k-c:a aac -b:a 192kBetter than MP3 at equivalent bitrate
DAW / editingWAV-c:a pcm_s16le -ar 44100No encoding loss, widest DAW support
Source already target formatCopy-c:a copyNo re-encode, instant, lossless

Process

1. Probe audio streams

ffprobe -v quiet -print_format json -show_streams "$INPUT" | \
  python3 -c "
import json, sys
streams = [s for s in json.load(sys.stdin)['streams'] if s['codec_type']=='audio']
for i, s in enumerate(streams):
    print(f'Stream {i}: {s[\"codec_name\"]} {s.get(\"bit_rate\",\"?\")} bps {s.get(\"channel_layout\",\"?\")}')
"

2. Determine format

Apply the decision tree above if the user didn't specify. If the source audio codec already matches the target, use -c:a copy to avoid transcoding.

If multiple audio streams exist, ask the user which to extract — or use -map 0:a to extract all. Once the user responds, apply -map 0:a:N (where N is the zero-based stream index they chose) or -map 0:a for all streams in the Phase 3 command.

3. Construct command

# General pattern (-vn drops the video stream entirely):
ffmpeg -i "$INPUT" -vn [FORMAT_FLAGS] "$OUTPUT"

# Examples:
ffmpeg -i video.mp4 -vn -c:a libmp3lame -q:a 0 audio.mp3        # MP3 VBR best quality
ffmpeg -i video.mp4 -vn -c:a libmp3lame -b:a 128k podcast.mp3   # MP3 128k CBR
ffmpeg -i video.mp4 -vn -c:a flac archive.flac                   # FLAC lossless
ffmpeg -i video.mp4 -vn -c:a aac -b:a 192k mobile.aac           # AAC
ffmpeg -i video.mp4 -vn -c:a pcm_s16le -ar 44100 edit.wav       # WAV for DAW
ffmpeg -i video.mp4 -vn -c:a copy original.m4a                  # Copy audio stream

4. Confirm and run

Show: detected source codec and bitrate, chosen output format, output path. Wait for approval, then run.

Report output file size and duration: ffprobe -v quiet -show_format "$OUTPUT" | grep -E "duration|size"

Key Decisions

Preserve generation quality: avoid transcoding chains that degrade source fidelity. Each decision below is an application of this principle.

  • Lossy-to-lossy warning: if the source is already lossy (MP3, AAC, OGG) and the user wants a different lossy format, warn them that re-encoding degrades quality. Recommend keeping the source format or using -c:a copy where container compatibility allows.
  • For files >1 hour, ask whether the user wants the full file or a specific range — trimming can be added with -ss and -to before -vn.
  • M4A vs AAC: AAC is the codec, M4A is the container. Use .m4a extension for Apple device compatibility; use .aac for a raw stream.

Extract Frames

Arguments

Parse the user's request for:

  • video path (required): path to the video file
  • --last: extract last frame of each shot instead of first
  • --first --last or --all: extract both first and last frames
  • --shots N,N,N: only process specific shot numbers (1-indexed)
  • --threshold X: override auto-detected threshold (skip user confirmation)

Default: extract first frame of every shot.

Workflow

Phase 0: Setup

  1. Validate the video file exists.
  2. Get video metadata via ffprobe:
ffprobe -v error -show_entries format=duration -show_entries stream=r_frame_rate,width,height,codec_name -of default "$INPUT"
  1. Parse fps (needed for last-frame calculation) and duration.
  2. Create output directory next to the video: {video_basename}_frames/. If it already exists, check for scores.txt — if present, skip Phase 1.

Phase 1: Score Dump

Dump per-frame scene scores for the entire video:

ffmpeg -i "$INPUT" -vf "select='gte(scene,0)',metadata=print:file=$OUTPUT_DIR/scores.txt" -fps_mode vfr -f null - 2>&1

This is the expensive step. The output file scores.txt contains blocks like:

frame:0    pts:0       pts_time:0.000000
lavfi.scene_score=0.000000

Phase 2: Cut Detection

Parse scores.txt with this awk one-liner to get distribution + all candidate frames:

awk '
/pts_time/ { split($0, a, "pts_time:"); ts=a[2]+0 }
/scene_score/ { split($0, a, "="); score=a[2]+0;
  if (score < 0.01) b1++;
  else if (score < 0.05) b2++;
  else if (score < 0.10) b3++;
  else if (score < 0.20) b4++;
  else b5++;
  total++;
  if (score > max) max=score;
  if (score > 0.05) printf "  ts=%.3fs  score=%.6f\n", ts, score;
}
END {
  print "\n--- Distribution ---";
  printf "< 0.01:      %d (%.1f%%)\n", b1, b1/total*100;
  printf "0.01 - 0.05: %d (%.1f%%)\n", b2, b2/total*100;
  printf "0.05 - 0.10: %d (%.1f%%)\n", b3, b3/total*100;
  printf "0.10 - 0.20: %d (%.1f%%)\n", b4, b4/total*100;
  printf "0.20+:       %d (%.1f%%)\n", b5, b5/total*100;
  printf "Max score:   %.6f\n", max;
}' "$OUTPUT_DIR/scores.txt"

Step 2a — Startup artifact filter: Discard any frames in the first 0.5s where score > 0.05 (a fixed preliminary value — the final user-confirmed threshold is not known yet). Fade-ins from black or codec initialization commonly produce score=1.0 spikes at t=0.03-0.08s that are not real cuts. After discarding these, recompute max score from the remaining frames.

Step 2b — Branch on max score. If max score (after startup filter) < 0.05, the video has no cuts:

  • Report: "No shot boundaries detected — single continuous shot."
  • Extract only frame at t=0 (or t=1.0s if t=0 is a black frame — check file size, <50KB indicates black).
  • Skip threshold confirmation.

Step 2c — Gap analysis and threshold. If max score >= 0.05, use the raw candidates (all frames with score > 0.05, after startup filter) to find the noise ceiling and the lowest-scoring candidate. Place the proposed threshold at the midpoint of the gap. Present to user via AskUserQuestion:

  • Score distribution summary
  • Gap analysis (noise ceiling → lowest cut, gap width)
  • Proposed threshold and resulting shot count
  • Options: Accept proposed (Recommended), Lower threshold, Higher threshold, Custom value

If --threshold was provided, skip confirmation and set $THRESHOLD_VALUE directly. Otherwise set $THRESHOLD_VALUE to the user-confirmed value before proceeding.

Step 2d — Run-based dedup. Using $THRESHOLD_VALUE from Step 2c, identify cut points. A "run" is a sequence of consecutive frames where every frame scores above threshold. The principle: an aftershock immediately follows its parent cut (consecutive frames both above threshold), while a real cut always rises from the noise floor (preceded by at least one below-threshold frame).

awk -v THRESHOLD="$THRESHOLD_VALUE" '
/pts_time/ { split($0, a, "pts_time:"); ts=a[2]+0 }
/scene_score/ { split($0, a, "="); score=a[2]+0;
  if (score > THRESHOLD) {
    if (!in_run) { run_best_ts = ts; run_best_score = score; in_run = 1; }
    else if (score > run_best_score) { run_best_ts = ts; run_best_score = score; }
  } else {
    if (in_run) { printf "%.3f %.6f\n", run_best_ts, run_best_score; in_run = 0; }
  }
}
END { if (in_run) printf "%.3f %.6f\n", run_best_ts, run_best_score }
' "$OUTPUT_DIR/scores.txt"

This keeps the peak frame of each run and discards aftershocks within the same run. It correctly handles:

  • Standard cuts: isolated spikes → each kept (run length 1)
  • Cuts with aftershocks: 2-3 consecutive high frames → peak kept, echoes discarded
  • Rapid montages: each cut separated by noise frames → all kept, even at 0.12s intervals

Phase 3: Frame Extraction

For each detected cut point (plus t=0 for shot 1):

First frame (default):

ffmpeg -y -ss $TIMESTAMP -i "$INPUT" -frames:v 1 -update 1 "$OUTPUT_DIR/shot_${NUM}_${TIME}s.png"

Last frame (--last):

  • For shots 1 through N-1: last_time = next_shot_timestamp - (1/fps)
  • For final shot: last_time = duration - (2/fps) (use 2 frames back, not 1 — seeking to duration - 1/fps can produce empty files near the end of some videos)
ffmpeg -y -ss $LAST_TIME -i "$INPUT" -frames:v 1 -update 1 "$OUTPUT_DIR/shot_${NUM}_last_${TIME}s.png"

If a last-frame extraction produces an empty file (0 bytes), back off by another frame and retry.

Both (--first --last or --all): extract both per shot.

Filtered (--shots 3,5,7): only extract for the specified shot numbers.

Output

  • Directory: {video_basename}_frames/ next to the input video
  • First frames: shot_01_0.00s.png, shot_02_1.63s.png, ...
  • Last frames: shot_01_last_1.60s.png, shot_02_last_3.77s.png, ...
  • scores.txt always retained for re-runs at different thresholds

Report to user: total shots detected, shot list with timestamps, output directory path.

Re-run Behavior

If scores.txt already exists in the output directory, skip Phase 1 entirely and go straight to Phase 2 analysis. This makes threshold iteration instant — the user can re-run with --threshold 0.15 without waiting for the score dump again.

Shell Portability

Use pipe-based loops for frame extraction instead of array syntax (zsh handles for over arrays differently than bash):

echo "0.000 2.480 4.280" | tr ' ' '\n' | awk '{printf "%02d %s\n", NR, $1}' | while read LABEL TS; do
  TS_FMT=$(printf "%.2f" "$TS")
  ffmpeg -y -ss "$TS" -i "$INPUT" -frames:v 1 -update 1 "$OUTPUT_DIR/shot_${LABEL}_${TS_FMT}s.png" 2>/dev/null
done

Edge Cases

  • Single continuous shots: Handled by step 2b. Common in fashion videos with rack-focus reveals, slow wardrobe progression, or single-take lifestyle shots.
  • Startup artifacts: Fade-ins from black produce score=1.0 at t=0.03-0.08s. Step 2a discards frames with score > 0.05 in the first 0.5s. If t=0 itself is a black frame (PNG < 50KB), extract at t=1.0s instead.
  • Aftershock spikes: Consecutive above-threshold frames (a cut + its echo). Run-based dedup in step 2d keeps only the peak of each run — no temporal window needed.
  • Rapid montages: Videos where shots are 2-4 frames long (0.08-0.16s). Each cut rises from the noise floor with 1-2 noise frames between spikes. Run-based dedup correctly preserves every cut because no two spikes are frame-adjacent. Report montage segments to the user: "Detected rapid montage from Xs-Ys with N shots."
  • Dissolves/fades: Score gradually ramps over multiple frames — forms a single run. Run-based dedup takes the peak frame as the cut point.
  • Empty file on seek: If ffmpeg produces a 0-byte PNG (common near video end), back off by one frame interval and retry.

Requires GEMINI_API_KEY environment variable and uv package manager.

Workflow

  1. Understand — Determine mode (t2i, i2i, multi-reference), gather parameters (model, aspect ratio, resolution, output path). If the prompt requires precise execution (specific pose, asymmetric framing, exact crop), default to --batch 3 or --batch 4 and surface this to the user — image generation is stochastic and precise directives hit ~50% per seed. Exit: mode, parameters, and batch size are clear.
  2. Craft prompt — Default to the minimal prompt that can carry the intent: t2i uses narrative prose; i2i/multi-reference uses a reference block plus the minimal directive. Apply the Core checklist (always, for the matching mode). Reach into the Escalation toolkit only on a known-hard signature — a detail/geometry-fidelity shot — or after a batch shows drift; then add only the specific lock for the attribute that is drifting, not the whole kit. Over-constraining a simple edit degrades it as surely as under-specifying a complex one. Exit: prompt written, Core items satisfied, escalation tools added only where a signature or observed drift justifies them.
  3. Confirm — Show the user the exact prompt, input images (if any), model, resolution, aspect ratio, and batch size. Ask for confirmation. Exit: user approves.
  4. Generate — Run the script with confirmed parameters. Exit: images are saved and displayed.
  5. Iterate — Present results and evaluate against intent before offering refinements. Evaluation order by mode: t2i — subject correctness, composition, style fidelity. i2i edit — the changed element looks right, nothing else changed. Multi-reference composition — the primary transferred attribute matches its source reference FIRST (for a detail shot, the construction geometry — width, edge shape, count, angle), secondary consistency (identity, environment) holds SECOND, staging (lighting, composition, framing) THIRD. Decide what's primary per task. Cherry-pick the winning frame from the batch rather than re-prompting for consistency past ~75%. Exit: user is satisfied or moves on.

Default Output & Logging

When the user doesn't specify a location, save images to:

~/Documents/generated images/

Every generated image gets a companion .md file with the prompt and model used (e.g., logo.png → logo.md).

When gathering parameters (aspect ratio, resolution), offer the option to specify a custom output location.


Core Prompting Principle

Describe scenes narratively, not as keyword lists. Gemini's language model parses prose with full semantic understanding — narrative prompts encode spatial relationships, mood, and intent that comma-separated tags cannot express. Tag-style prompts lose compositional meaning and produce generic results.

Bad:  "cat, wizard hat, magical, fantasy, 4k, detailed"

Good: "A fluffy orange tabby sits regally on a velvet cushion, wearing an ornate
       purple wizard hat embroidered with silver stars. Soft candlelight illuminates
       the scene from the left. The mood is whimsical yet dignified."

Describe positively, never via negation. Every concept named in a prompt biases the output toward that concept — even when preceded by "not", "no", or "do not". Diffusion models condition on tokens regardless of polarity. To exclude X, either (a) name a positive alternative that fills the same role, or (b) scope the prompt so X has no place to land.

Bad:   "A clean studio backdrop. No warm tones, no cream, no beige, no tan."
Good:  "A clean cool-neutral gray studio backdrop with subtle blue undertones."

Bad:   "A headshot with no harsh shadows on the face, no distracting background."
Good:  "A headshot on a clean neutral gray backdrop, even soft frontal fill light
        that flatters the face."

This rule applies everywhere in the skill — t2i prompts, i2i directives, reference role descriptions, and framing instructions.

Name sources explicitly — leave no ambiguity in references. Every element in the prompt should trace to a specific source: "the man from Image 2" not "this man"; "the shirt from Image 3" not "the shirt". Ambiguous references bind to whichever source the model weights most, which is never reliably the right one. This isn't about over-describing — don't re-describe what the reference already shows. It's about making each reference point to exactly one source.

A useful formula: [Subject] doing [Action] in [Context]. [Camera/Composition]. [Lighting]. [Style]. [Constraint]. Not every prompt needs every element — match detail to intent. If the user has a specific vision, be prescriptive (exact descriptions); if exploring, be open (general direction, let the model decide details). Ask if unclear.

Advanced Prompting Techniques

Hyper-specificity: Be precise about quantities, positions, and attributes. "Three red apples arranged in a triangle on a wooden table" outperforms "some apples on a table." Every vague word is a degree of freedom the model fills arbitrarily.

Context and intent: State the purpose. "A hero image for a coffee brand landing page" produces different results than "a photo of coffee" even if the visual subject is the same, because intent shapes composition, mood, and framing.

Step-by-step instructions: For complex scenes, break the prompt into sequential directives. "Start with a wide desert landscape. Place a lone figure walking left-to-right in the lower third. Behind them, a massive sandstorm approaches from the right."

Exclusion via positive constraint: When something must be absent from the output, do not name it under a negation. Either name a positive alternative ("clean unbranded surface" instead of "no logos") or scope the scene so the unwanted element has no place to land ("a closed laptop on the desk" makes a screen impossible to render). Naming X under "no X" makes X more likely, not less.

Camera control: Specify shot type (extreme close-up, medium shot, aerial), lens (fisheye, telephoto), and camera angle (low angle, bird's eye, Dutch angle) to control framing precisely.

Editing with reference images follows different principles — see references/editing-guide.md.


Key Editing Principles

Editing prompts direct changes rather than describing scenes. Point to what the model can see; describe only what it cannot. Specify intentionally — every adjective, color word, or preservation clause beyond the minimum competes with the reference image and degrades fidelity. The reliable shape is a reference block plus one Replace directive — the verb's implicit scope handles preservation, no stop clause needed. Details in editing-guide.md.

For multi-reference work (3+ images), use per-reference role assignment: one sentence that assigns each reference its specific contribution ("the facade from Image 2; the car from Image 3; the sky and lighting from Image 1") — see editing-guide.md "Per-Reference Role Assignment".

Base image goes first in --input — it becomes Image 1 in the prompt. Gemini numbers images sequentially from input order. Reference block labels must match input order exactly.

Names invoke aesthetics directly — referencing "shot on Kodak Portra 400" produces its characteristic look more reliably than describing warm skin tones and pastel highlights.


References

Load the relevant reference during prompt crafting (workflow step 2):


Configuration

Model Selection

Nano Banana (default)Nano Banana Pro
SpeedFast, high-volumeSlower, higher quality
Resolutions0.5K, 1K, 2K, 4K1K, 2K, 4K
Extra ratios1:4, 4:1, 1:8, 8:1—
Thinking modeYes (minimal/low/medium/high)No
Image search groundingYesNo
Max references1411 (6 objects + 5 characters)
Text renderingAdvancedStandard

Default to Nano Banana for most requests. Use Nano Banana Pro when the user explicitly asks for maximum quality or when Nano Banana results need refinement.

Aspect Ratios

Both models: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 Nano Banana only: 1:4, 4:1, 1:8, 8:1

Resolutions

  • 0.5K (~512px) — fast preview (Nano Banana only)
  • 1K (~1024px) — default, fast
  • 2K (~2048px) — high quality
  • 4K (~4096px) — maximum detail

Defaults: 1K resolution, batch 1, aspect ratio auto-detected from base image (first input, or 1:1 if no images). Use 0.5K for quick previews and iteration (Nano Banana only). Use 2K for higher quality requests, 4K only when high detail is explicitly needed.

Thinking Mode (Nano Banana only)

Nano Banana supports controllable thinking levels that improve complex prompt interpretation:

  • minimal (default) — fastest, suitable for straightforward prompts
  • low/medium — balanced reasoning for moderately complex scenes
  • high — maximum reasoning for complex multi-element compositions, precise text rendering, or intricate spatial layouts

Use --thinking high when the prompt involves precise spatial relationships, multiple text elements, or detailed composition requirements. For i2i editing, thinking mode also helps with multi-reference composition (3+ images), precise text/sign placement on existing scenes, and complex spatial edits where element positioning matters.


Script Usage

One unified script handles all modes: t2i, i2i, and multi-reference composition. Nano Banana is the default model.

# Text-to-image (t2i) — uses Nano Banana by default
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "A serene mountain lake at dawn" --output landscape.png

# Nano Banana Pro model
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "A serene mountain lake at dawn" --output landscape.png --model pro

# Image-to-image editing (i2i)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Make it sunset colors" --input photo.png --output edited.png

# Multi-reference composition
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Combine the cat from image 1 with the background from image 2" --input cat.png --input background.png --output composite.png

# With options (aspect ratio, resolution, thinking, batch, grounding, format)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Logo for 'Acme Corp'" --output logo.png --aspect 1:1 --resolution 2K --thinking high

Script Options

FlagShortDescription
--prompt-pImage description or edit instruction (required)
--output-oOutput file path (required)
--input-iInput image(s) for editing/composition (repeatable, up to 14)
--model-mModel: nano-banana (default) or pro
--aspect-aAspect ratio (auto-detects from base image / first input, or 1:1)
--resolution-rOutput resolution: 0.5K, 1K, 2K, or 4K (default: auto-detect or 1K)
--grounding-gEnable Google Search web grounding
--image-groundingEnable image search grounding (Nano Banana only, use with --grounding)
--thinking-tThinking level: minimal, low, medium, high (Nano Banana only)
--quality-qOutput compression quality 1-100 (JPEG only)
--format-fOutput format: png (default) or jpeg
--batch-bGenerate multiple variations: 1-4 (default: 1)
--jsonOutput results as JSON for agent consumption
--quietSuppress progress output (MEDIA lines still printed)
--max-input-dimLong-edge size inputs are shrunk to before upload (default: 2048); raise it to keep fine texture in a close crop

The script auto-detects resolution and aspect ratio from input images when flags are omitted, and automatically resizes large inputs (>2048px, or --max-input-dim) before sending to the API.


Pre-Generation Checklist

Core items are the floor — apply them to every prompt of the matching mode. The Escalation toolkit is opt-in: skip it entirely for simple t2i and single-element edits. Reach in only on a known-hard signature (a detail/geometry-fidelity shot) or after a batch shows drift — and then add only the lock for the attribute that is actually drifting. Each added constraint costs fidelity on everything else, so escalation scales with how many independent things can drift, not with how ambitious the prompt is.

Core — t2i (always)

  • Narrative description (not keyword list)?
  • Positive framing throughout — no "no X" / "not X" / "do not X" clauses anywhere in the prompt?
  • Camera/lighting details for photorealism?
  • Text in quotes, font style described? (if the image has text)
  • Aspect ratio appropriate for use case?
  • Model choice appropriate? (Nano Banana default; Nano Banana Pro for max quality)
  • Thinking level set for complex prompts? (Nano Banana only)
  • Batch size matches precision needs? (--batch 3 or --batch 4 for precise pose / framing / asymmetric directives)

Core — i2i / multi-reference (always)

  • Reference block at start of prompt labeling each image's role?
  • Reference roles positive-only — lists what to USE from each ref, never what to ignore? (see editing-guide.md "Reference Block")
  • Minimal directive pattern? (Reference block + one Replace directive — no "do not change anything else" stop clause, no decorative preservation clauses)
  • Positive framing throughout the directive? (no negation anywhere, including locks and composition clauses)
  • Base image first in --input (Image 1), and prompt labels match input order? (mislabeled roles cause character drift)
  • Only one change per prompt? (split competing directives into sequential passes)
  • When extracting/transferring elements: explicitly named each element rather than generic "outfit/object from image X"?
  • One reference carrying an element you need to preserve while another reference could compete with it? → add CRITICAL — [element] proactively: assign the source reference explicitly ("Image 1 is the sole identity source. Image 2 is scoped to [attribute] only."). Do not wait for drift — role competition defeats text directives silently.
  • No color labels competing with reference image? (color words override visual reference — see editing-guide)
  • Base image has minimal accessories that could contaminate? (bags, hats, sunglasses bleed into output)
  • Reference count within model limits? (Nano Banana: 14, Nano Banana Pro: 11)
  • For 3+ references: per-reference role-assignment sentence? (one sentence assigning each image its contribution — see editing-guide.md "Per-Reference Role Assignment")
  • For photorealistic human shots: skin & finish locked? (the one near-universal CRITICAL section — generative skin drifts to plastic/retouched)

Escalation toolkit — reach for only on a hard signature or observed drift

  • An attribute (identity, lighting/color, orientation, drape) drifting across the batch? Lock that specific attribute in its own ## CRITICAL — section, positively phrased — without over-constraining the stable ones. (see editing-guide.md "Constraint Locking with CRITICAL Sections")
  • Detail shot whose construction won't hold? Geometry lock via per-attribute enumeration, not generic "match exactly". (see capability-patterns.md "Geometry Lock for Detail Shots")
  • Nano Banana + --thinking high with 3+ references and weak adherence? Add the inventory preamble. ("Silently inventory the design-critical details: ...")
  • Follow-up shot from the same set? Continuity assertion. ("from the same set as Image N: same subject, same setting, same light" — see editing-guide.md "Continuity Assertion")
  • Campaign with a locked hero image? Collapse to two-input form — hero as bundle-source + the single new-attribute reference. (see editing-guide.md "Single-Reference Collapse")

Video GIF

Convert a video clip to a high-quality GIF using the mandatory 2-pass palette workflow.

Single-pass GIF always produces banding and color artifacts. The palettegen → paletteuse pipeline analyzes the actual clip to build an optimal 256-color palette, then renders with it. Never skip this.

Process

1. Gather parameters

Ask for any not already provided in the request:

  • Start time — default 0
  • Duration or end time — required; warn if >30s (file size grows rapidly)
  • Width — default 480px; height auto-calculated to preserve aspect ratio
  • FPS — default 15; higher = smoother + larger file

If the user asks about aspect ratio or the source has unusual dimensions, probe first:

ffprobe -v quiet -print_format json -show_streams "$INPUT" | \
  python3 -c "import json,sys; s=[s for s in json.load(sys.stdin)['streams'] if s['codec_type']=='video'][0]; print(s['width'], 'x', s['height'])"

2. Build the 2-pass command

Pass 1 — generate optimized palette:

ffmpeg -ss $START -t $DURATION -i "$INPUT" \
  -vf "fps=$FPS,scale=$WIDTH:-1:flags=lanczos,palettegen=stats_mode=full" \
  /tmp/palette_$$.png -y

Pass 2 — render GIF using palette:

ffmpeg -ss $START -t $DURATION -i "$INPUT" -i /tmp/palette_$$.png \
  -lavfi "fps=$FPS,scale=$WIDTH:-1:flags=lanczos [x]; [x][1:v] paletteuse=dither=bayer:bayer_scale=5" \
  "$OUTPUT" -y

Use $$ (shell PID) in the palette temp path to avoid collisions with concurrent runs.

3. Confirm before running

Show the full 2-pass command and estimated output path. Add a size warning if duration × fps is large (rough heuristic: >20s at 15fps at 480px → likely >10MB).

4. Run both passes, then clean up

rm -f /tmp/palette_$$.png

Report output path and file size.

Key Decisions

  • stats_mode=full on palettegen analyzes the entire clip — not just the first frame — for better palette coverage across motion.
  • dither=bayer:bayer_scale=5 is the sweet spot for photographic content. Use dither=none for flat-color content (illustrations, slides, screen recordings with solid backgrounds).
  • -ss placed before -i uses container-level fast seek. Apply to both passes for consistent start points and dramatically faster seeks on long source files.
  • flags=lanczos on scale gives sharper downsampling than the default bilinear.
  • To control loop count, add -loop $N to pass 2: 0 = infinite, 1 = play once, 2 = play twice.

Video Social

Prepare video for social media platforms: correct aspect ratios, resolutions, bitrates, and container settings.

Platform Presets

PlatformAspectMax ResolutionMax DurationVideo BitrateAudio
Instagram Feed4:5 portrait or 1:11080×1350 / 1080×108060s3.5 MbpsAAC 128k
Instagram Reels9:161080×192090s8 MbpsAAC 192k
TikTok9:161080×192010min8 MbpsAAC 192k
YouTube Shorts9:161080×192060s8 MbpsAAC 192k
YouTube Standard16:91920×1080unlimited8 Mbps (1080p)AAC 192k
Twitter / X16:9 or 1:11920×1200140s25 Mbps capAAC 128k
Facebook16:9 or 9:161920×1080240min4 MbpsAAC 128k
LinkedIn16:91920×108010min5 MbpsAAC 128k

Process

1. Identify platform

If the request is ambiguous (e.g., "make it vertical"), ask which platform — bitrate and audio requirements differ.

2. Probe source

ffprobe -v quiet -print_format json -show_streams -show_format "$INPUT"

Extract: width, height, duration, existing bitrate, audio codec.

3. Determine required transforms

Compare probe output against the platform row in the presets table. Apply only the transforms that are actually needed:

  • Aspect ratio mismatch → crop or pad (see Key Decisions for the choice rule)
  • Resolution too large → scale down (never upscale; social platforms reject oversized files at upload)
  • Duration exceeds platform limit → trim; confirm cut point with user first
  • Bitrate over limit → re-encode with target bitrate (platforms reject or silently degrade over-bitrate uploads)

Exit condition: when all four properties (aspect ratio, resolution, duration, bitrate) are within platform bounds and -movflags +faststart will be set, proceed to Step 4. If source already matches all properties, skip to Step 5 with a simple re-encode plan.

4. Construct command

Crop to fit (preferred when subject is centered):

# 16:9 source → 9:16 (1080×1920), center crop:
ffmpeg -i "$INPUT" \
  -vf "crop=ih*9/16:ih,scale=1080:1920" \
  -c:v libx264 -b:v 8000k \
  -c:a aac -b:a 192k \
  -movflags +faststart "$OUTPUT"

Pad to fit (preserves full frame, adds letterbox/pillarbox):

# 16:9 source → 9:16 with black bars:
ffmpeg -i "$INPUT" \
  -vf "scale=1080:-2,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:black" \
  -c:v libx264 -b:v 8000k \
  -c:a aac -b:a 192k \
  -movflags +faststart "$OUTPUT"

Square (1:1) from 16:9 — center crop:

ffmpeg -i "$INPUT" \
  -vf "crop=ih:ih,scale=1080:1080" \
  -c:v libx264 -b:v 3500k \
  -c:a aac -b:a 128k \
  -movflags +faststart "$OUTPUT"

5. Confirm

State: crop vs. pad choice, any trim, output resolution and bitrate, output path. Wait for approval.

6. Run and verify

After encoding, verify bitrate: ffprobe -v quiet -show_format "$OUTPUT" | grep bit_rate

Key Decisions

  • Always include -movflags +faststart — relocates the moov atom to the file start, enabling progressive playback before full download. Required for all social platforms.
  • Crop vs. pad: default to crop for talking-head or centered subjects; default to pad for wide scenic shots or text-heavy content. When the user says "don't cut anything off", use pad. When uncertain with off-center subjects, ask before running.
  • Never upscale: if source is smaller than target resolution, scale to fit within bounds or keep original dimensions.

Sponsors

Details

Marketplace
gupsammy/Claudest
Source
plugins/claude-content
Category
Community

More from gupsammy/Claudest

All 8