Motion Craft

Motion Craft

Use FFmpeg and FFprobe to produce polished, reliable video edits. Work locally; do not upload the user's media to third-party services.

Core rules

1. Never overwrite the source unless the user explicitly requests it.
2. Inspect the source before designing the edit:
   • video/audio streams
   • duration
   • dimensions, frame rate, pixel format, and sample rate
   • rotation and color metadata when relevant
3. For visually targeted edits, inspect representative frames before rendering. Use frames near every requested transition or effect boundary.
4. Preserve the source's aspect ratio and frame rate unless the requested output requires a change. Explain intentional crops.
5. Preserve audio unless the user asks to remove or replace it.
6. Prefer one coherent -filter_complex graph over repeated lossy renders.
7. Put complicated filter graphs in a temporary filter script rather than fighting shell escaping. Delete temporary files after verification.
8. Show errors instead of returning a success-shaped fallback.
9. Render to a new, clearly named file beside the source unless the user gives another destination.
10. If background music would suit the requested edit but the user has not provided a music/audio file or URL, ask whether they want music before the final render. Let them provide a local path or authorized URL, or choose no music. Do not delay a silent/voice-only edit when music is clearly unwanted. Never download copyrighted music from an unauthorized source.
11. Match generated graphics to the source video's visual language. Sample dominant/accent colors from representative frames or use supplied brand assets instead of applying a generic gradient. Match typography weight, corner radius, spacing, contrast, and motion character where practical.
12. If the source does not provide a clear visual direction and the user has not supplied one, ask for optional brand choices: logo, palette/hex colors, fonts, reference image/video, and preferred tone. Offer to infer a tasteful palette from the footage when they have no brand guide.
13. For screen recordings, inspect the beginning, every splice boundary, and the ending for recorder controls, cursor toolbars, notification overlays, blank application redraws, and loading flashes. Trim or replace those frames rather than leaving capture artifacts in the final video.

Ensure FFmpeg is available

Check both tools before any edit:

powershellCopy code
ffmpeg -hide_banner -version
ffprobe -hide_banner -version

On macOS/Linux, use the equivalent shell commands.

If either command is unavailable, install FFmpeg with the platform's trusted package manager. Tell the user what will be installed. Do not download or run a random executable from an unofficial mirror.

Windows

Prefer WinGet:

powershellCopy code
winget install --id Gyan.FFmpeg.Essentials --exact --accept-package-agreements --accept-source-agreements

If WinGet is unavailable, use Chocolatey only when it is already installed:

powershellCopy code
choco install ffmpeg -y

FFmpeg's official download page links to supported Windows builds: https://ffmpeg.org/download.html#build-windows.

macOS

Prefer Homebrew when available:

bashCopy code
brew install ffmpeg

Debian or Ubuntu

bashCopy code
sudo apt-get update
sudo apt-get install -y ffmpeg

Fedora

Use the configured Fedora/RPM Fusion repositories:

bashCopy code
sudo dnf install -y ffmpeg

Arch Linux

bashCopy code
sudo pacman -S --needed ffmpeg

If installation requires administrator approval, repository configuration, or an unavailable package manager, ask the user rather than bypassing controls. After installation, open a fresh shell if needed and verify both commands.

Inspect the media

Start with:

bashCopy code
ffprobe -v error -show_entries format=duration,format_name:stream=index,codec_type,codec_name,width,height,r_frame_rate,avg_frame_rate,pix_fmt,sample_rate,channels:stream_tags=rotate -of json "input.mp4"

For visual work, extract low-cost review frames:

bashCopy code
ffmpeg -hide_banner -loglevel error -ss 00:00:05 -i "input.mp4" -frames:v 1 "frame-5s.png"

Use a contact sheet or several timestamped frames when scene boundaries are not known. Do not infer crop coordinates or overlay timing from the filename alone.

Plan edits precisely

Translate the request into a timeline before rendering:

For screen recordings, match callouts and lower thirds to what is visibly onscreen. For voiceovers, compare narration and video durations. If narration is longer, prefer a user-appropriate solution such as extending the final frame, slowing a suitable section, or revising timing; do not silently truncate.

Default delivery profile

Unless the user requests another codec or container, produce broadly compatible MP4:

bashCopy code
ffmpeg -i "input.mp4" ... -c:v libx264 -preset medium -crf 18 \
  -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart "output.mp4"

• Use CRF 18-20 for high-quality delivery and 21-23 for smaller previews.
• Use -map 0:a? or optional audio mappings when input audio may be absent.
• Copy streams only when no filter requires re-encoding.
• Keep a consistent audio sample rate across concatenated segments, typically 48 kHz or the source rate.
• Use hardware encoding only when useful and available. Prefer quality and portability; fall back to software encoding if hardware initialization fails.

Cinematic editing patterns

Smooth focus-card animation

For educational screen recordings:

1. split the source into base, background-effect, and foreground streams.
2. crop the interface region that needs focus.
3. Blur and optionally dim the background with gblur, smartblur, eq, or a translucent color overlay.
4. Animate the cropped card with per-frame scale and overlay expressions.
5. Add a softened shadow using format=yuva420p, pad, colorchannelmixer, and gblur.
6. Use smoothstep easing (3*p*p - 2*p*p*p) instead of linear motion.
7. Reverse the animation cleanly back to the original location.

Keep the foreground sharp. Verify frames before, during, and after the effect.

This pattern explicitly supports a blurred background with a cropped overlay on top:

• crop the important UI region from a clean source branch
• blur/dim a full-frame branch behind it
• center or reposition the crop as a sharp card
• add restrained scale/position easing, border, and soft shadow
• return the card to its source location or dissolve it cleanly

Use exact crop coordinates confirmed from review frames. Do not enlarge beyond readable source resolution, and do not animate scale when a stable fixed overlay communicates the point better.

Kinetic cards and comparison layouts

Support modern animated-card compositions, including:

• cards sliding or easing into a grid
• staggered image, title, metric, or feature cards
• before/after comparisons
• split-screen raw-versus-polished demonstrations
• stacked callouts and step cards
• floating UI panels over a blurred or color-treated background

Build cards from cropped video/image streams, drawbox, drawtext, alpha channels, shadows, and overlay. Use smoothstep or cubic easing for position and opacity. Prefer animating overlay position/alpha over continuously rescaling the source; when scale animation is needed, keep dimensions even, normalize SAR, use a consistent frame rate, and inspect consecutive frames for jitter.

Keep motion hierarchy clear: one primary card or action at a time, restrained staggering, sufficient hold time for reading, and clean exits. Never cover the interaction or UI detail the user is trying to demonstrate.

Stable screen-recording edits

• Prefer fixed framing for UI demonstrations unless movement clearly improves comprehension. Unnecessary per-frame zooming can appear jittery, especially when low-frame-rate recordings are accelerated.
• When accelerating 10/15 fps recordings, normalize the output frame rate and inspect consecutive frames. Use frame interpolation only when it improves the result without creating cursor/UI warping.
• Remove recorder controls and stop-recording overlays at clip beginnings and endings. Cut before they appear; do not hide them with unrelated graphics.
• Detect blank application redraws or single-frame flashes with a contact sheet and consecutive-frame inspection. Remove the affected frame range and join adjacent clean states with a short video/audio crossfade.
• After replacing a time range, inspect several frames before, inside, and after the splice. Confirm the replacement has the intended exact duration so later audio and visual events remain synchronized.

Cinematic color treatment

Build restrained grades from filters such as:

• curves or colorlevels for contrast and black/white points
• colorbalance, colorchannelmixer, or lut3d for color separation
• eq for modest contrast, saturation, brightness, and gamma changes
• vignette for subtle edge falloff
• noise or gradfun for controlled texture/banding reduction
• unsharp for mild finishing sharpness

Avoid crushing shadows, clipping highlights, oversaturation, or aggressive vignettes. When exact color appearance matters, preserve or explicitly convert color-space metadata.

Titles, lower thirds, and captions

• Use drawtext for simple text and subtitles/ASS for sophisticated styling.
• Derive title-card and gradient colors from the footage, logo, thumbnail, or supplied brand reference. Check representative pixels/regions rather than guessing from memory.
• When brand direction is supplied, follow its palette, fonts, logo-safe space, contrast, and motion style. When it is absent, propose or infer a restrained palette and keep it consistent across titles, lower thirds, cards, and outro.
• Confirm the font exists on the machine. Quote and escape font paths safely.
• Use safe margins and readable contrast.
• Animate with time-based x, y, and alpha expressions.
• For gradient cards, generate the background, add subtle graphic elements, render text, create matching silent audio, and concatenate with normalized video/audio formats.
• Never burn captions into the picture unless requested; offer a subtitle track when editability or accessibility matters.
• Avoid placing banners over active interactions. Use whitespace, an unused region, a brief interstitial, or a separate card between demonstrations.

Smooth animated titles

Support polished opening titles, section titles, interstitials, and end cards:

• slide-and-fade text from an edge or nearby resting position
• masked/wipe reveals using a moving crop, alpha mask, or covering shape
• staggered eyebrow, headline, and subtitle entrances
• subtle scale settling (for example 102% to 100%), never repeated pulsing
• word- or line-based kinetic typography when the message benefits from it
• coordinated exits that finish before the next important visual action

Use smoothstep or cubic easing for x, y, alpha, and scale expressions. Avoid linear starts/stops. Keep the animation short enough to feel responsive but leave sufficient hold time to read the complete title.

Example timing model for a 3-second title:

Do not begin a social-media video with a visually empty title background when the platform may select its first frame as the thumbnail. Prefer a strong source frame with a title overlay, or begin with the visual hook and place the title as a short interstitial.

Animated lower thirds

Create lower thirds as coordinated components rather than text floating alone:

1. Use a brand-matched solid, translucent, blurred, or gradient-backed card.
2. Animate the card in first with eased position and alpha.
3. Reveal the primary label, then the secondary line with a short stagger.
4. Hold long enough to read.
5. Exit cleanly before it covers a new interaction or scene change.

Common layouts include:

• compact name/role card
• feature or chapter label
• numbered step indicator
• quote or key-stat callout
• pill label plus headline

Keep lower thirds inside title-safe margins, normally within the lower-left or lower-right unused region. Check the source at the entire display interval; placement that is safe on the first frame may cover UI or captions later.

For a modern treatment, combine drawbox/generated card layers, drawtext, alpha-capable formats, and overlay. Add a restrained shadow or backdrop blur when needed for contrast. Animate the group consistently so the background and text do not drift or jitter relative to each other.

Text-animation quality checks

• Confirm fonts exist or provide a portable fallback.
• Keep text sharp and high contrast at delivery resolution.
• Use consistent capitalization, weight, spacing, and punctuation.
• Never let text clip during its entrance/exit animation.
• Inspect the first fully visible frame, readable hold, and final exit frame.
• Check consecutive frames for scale/position jitter.
• Verify title and lower-third timing against the visible scene, not only the requested timestamp.
• Preserve caption readability and do not place decorative text over subtitles.

Transitions and scene changes

• Prefer xfade for deliberate transitions and acrossfade for matching audio.
• Normalize resolution, frame rate, time base, pixel format, channel layout, and sample rate before concatenation.
• Keep transition durations short and motivated; avoid using effects simply because they are available.

Reframing for social media

Common outputs:

• Landscape: 1920x1080 (16:9)
• Vertical: 1080x1920 (9:16)
• Square: 1080x1080 (1:1)

Use scale plus crop for full-frame output, or scale plus pad to retain all content. For screen recordings, inspect whether a fixed crop hides important UI; use animated reframing when the subject moves.

Generate narration with Edge TTS

When the user provides text and asks for a synthetic voiceover, use edge-tts when an online TTS service is acceptable. Edge TTS sends the narration text to Microsoft's online speech service, so tell the user before using it for sensitive or confidential text. It requires an internet connection.

Check whether it is available:

bashCopy code
edge-tts --help

If it is missing, prefer pipx when installed because it isolates the CLI:

bashCopy code
pipx install edge-tts

Otherwise install it with the active Python interpreter:

powershellCopy code
py -m pip install --user --upgrade edge-tts

On macOS or Linux:

bashCopy code
python3 -m pip install --user --upgrade edge-tts

If the command is not added to PATH, invoke the module through Python:

bashCopy code
python -m edge_tts --help

Do not install into an unrelated project environment or modify its dependency manifest unless the user requests that. If Python or pip is unavailable, install Python through the platform's trusted package manager or direct the user to https://www.python.org/downloads/, then retry.

List available voices rather than inventing a voice identifier:

bashCopy code
edge-tts --list-voices

Generate narration and matching subtitles:

bashCopy code
edge-tts --voice en-US-AvaNeural \
  --rate=+0% --volume=+0% --pitch=+0Hz \
  --text "Narration text" \
  --write-media "narration.mp3" \
  --write-subtitles "narration.srt"

For negative rate, volume, or pitch values, use the equals form such as --rate=-10%; otherwise the value may be parsed as another option.

Voiceover workflow:

1. Confirm the narration text, language, and requested tone.
2. List voices and choose one matching the language. If the user has no preference, use a clear general-purpose neural voice and state the choice.
3. Generate both audio and subtitles when useful.
4. Probe narration duration with FFprobe.
5. Compare narration duration with the video timeline.
6. Normalize gently, mix or replace audio, and verify synchronization.

Do not clone, imitate, or imply the identity of a real person. Use only the service's provided synthetic voices.

Mix audio and voiceover

• Use loudnorm carefully for delivery normalization.
• When no music is provided, ask the user to choose one of:
  • provide a local music file
  • provide an authorized downloadable audio URL
  • continue without background music
• If the user provides a URL, confirm it resolves directly to audio they are authorized to use. Do not rip audio from streaming or social-media services.
• Duck background audio under narration with sidechaincompress or timed volume automation.
• Apply short fades at cut boundaries to prevent clicks.
• Mix with amix only after matching sample formats/rates/layouts.
• Do not fabricate or clone a person's voice without clear authorization.

To replace the source audio with narration while copying unchanged video:

bashCopy code
ffmpeg -i "input.mp4" -i "narration.mp3" \
  -map 0:v:0 -map 1:a:0 -c:v copy -c:a aac -b:a 192k \
  -movflags +faststart "with-voiceover.mp4"

To keep full narration when it is longer than the video, calculate the duration difference and extend the final frame with tpad=stop_mode=clone. Do not use -shortest when it would truncate either required narration or video.

To duck looping background music under narration:

bashCopy code
ffmpeg -i "input.mp4" -stream_loop -1 -i "music.wav" -i "narration.mp3" \
  -filter_complex \
  "[1:a]volume=0.22,apad[music]; \
   [2:a]loudnorm=I=-16:TP=-1.5:LRA=11,apad,asplit=2[voice_sc][voice_mix]; \
   [music][voice_sc]sidechaincompress=threshold=0.03:ratio=8:attack=20:release=500[ducked]; \
   [ducked][voice_mix]amix=inputs=2:duration=longest:dropout_transition=2[aout]" \
  -map 0:v:0 -map "[aout]" -c:v copy -c:a aac -b:a 192k \
  -movflags +faststart -shortest "with-music-and-voiceover.mp4"

Trim/fade the music to the final timeline and confirm the narration remains clearly intelligible on headphones and typical laptop speakers.

Render workflow

1. Confirm source and output paths.
2. Probe media and inspect relevant frames.
3. Create a timestamped edit plan.
4. Validate a short or fast draft for complex filter graphs.
5. Inspect key frames from the draft.
6. Render the final quality output.
7. Verify the output with FFprobe and decode checks.
8. Remove temporary frames/filter scripts, leaving the source and final output.

For long renders, estimate complexity from duration and filters, use an appropriate preset, and report progress without restarting a successful render.

Verification

At minimum:

bashCopy code
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height,r_frame_rate,sample_rate,channels -of json "output.mp4"
ffmpeg -v error -i "output.mp4" -f null -

Also inspect frames at every transition boundary and confirm:

• expected duration and dimensions
• video decodes without errors
• audio exists when expected and stays synchronized
• overlays enter and exit at the intended times
• the source file remains unchanged

Report the final absolute path and a concise description of the applied edit.