Drop a video and a logo PNG in, get a branded MP4 back — one bash script, one API, four steps. No brew install ffmpeg, no filter-graph debugging, no servers.

Corner positioning, logo size, and margin are all flags. Swap a transparent PNG for a JPG if you don't need an alpha channel. Works with .mp4, .mov,.webm, .mkv.

What You'll Learn

• ✅ Multi-input transcodes — upload two files, combine them server-side with one filter graph
• ✅ FFmpeg overlay + scale — the exact filter the vast majority of watermark tutorials use, but served by an API instead of a local install
• ✅ Resolution-agnostic positioning — main_w-overlay_w-24 works on a 1080p or a 4K video, same string
• ✅ Transparent-PNG support — alpha channel is preserved through the overlay filter
• ✅ Parameter-driven script — corner, logo width, and margin are all flags, not hand-edits

How the Script Works

One run is a four-step pipeline:

1. Upload the video — POST /v1/upload/presigned-url + PUT + POST /v1/upload/confirm returns the gs:// URL
2. Upload the logo — same flow, any PNG or JPG
3. Render — POST /v1/transcodes with two inputs and one filter:

   [1:v]format=rgba,scale=<WIDTH>:-1[logo];[0:v][logo]overlay=<X>:<Y>

   format=rgba before scale keeps the alpha channel — without it scale defaults to a non-alpha pixel format and the overlay renders as a solid rectangle instead of compositing transparency.Scale the logo to the target width (height auto-fits), then overlay it on the video at the target corner.
4. Download — GET /v1/transcodes/:id/download returns a signed HTTPS URL

Positions

Pass one of br | bl | tr | tl | center as the fourth argument (default: br, bottom-right). Internally they map to FFmpeg overlay expressions using main_w/overlay_w so the positioning is resolution-independent:

What You'll Need

Cost Breakdown

Video processing minutes bill per transcode job, rounded up — a 30-second clip consumes 1 billable minute, a 61-second clip consumes 2. Logo inputs are images (no duration) and don't add to quota, so watermarking bills exactly the same as a plain re-encode at the same video length.

• • Free plan ($0/mo, 100 min): roughly 100 clips/month at ≤60s each
• • Starter plan ($19/mo, 2,000 min): roughly 2,000 clips/month
• • Pro plan ($89/mo, 12,000 min): roughly 12,000 clips/month

Check FFmpeg Micro pricing for the latest plan limits and features.

Run It — with sample assets (fastest)

The zip ships a fetch-demo-assets.sh that pulls a sample video and the FFmpeg Micro logo from ffmpeg-micro.com/samples:

export FFMPEG_MICRO_API_KEY=sk_live_xxx
./fetch-demo-assets.sh
./watermark.sh sample-video.mp4 sample-logo.png demo.mp4
open demo.mp4

Run It — with your own content

export FFMPEG_MICRO_API_KEY=sk_live_xxx
./watermark.sh my-video.mp4 my-logo.png branded.mp4 tl

That's it. branded.mp4 is your video with the logo in the top-left corner. Change the fourth arg for a different position.

Tweaks

• • Logo size: WATERMARK_WIDTH=200 ./watermark.sh ... (default 120). Height auto-scales to preserve aspect ratio.
• • Margin from edge: WATERMARK_MARGIN=40 ./watermark.sh ... (default 24).
• • Semi-transparent watermark: bake opacity into the PNG (8-bit alpha), or edit the filter in watermark.sh to add format=rgba,colorchannelmixer=aa=0.5 before the overlay stage.
• • Animated / moving watermark: swap the static overlay=X:Y expression for something dynamic like overlay='if(lt(mod(t,10),5),main_w-overlay_w-24,24)':24 to flip sides every 5s.

Related training

• • Image + narration → captioned zoom video — same bash + FFmpeg Micro shape, different filter (zoompan + auto-captions instead of overlay)
• • Make 100 shorts in under a minute — parallel bash pipeline driven by a CSV

Related endpoints

See the FFmpeg API documentation for the full reference. The endpoints this script uses:

• • POST /v1/upload/presigned-url + POST /v1/upload/confirm — direct-to-GCS uploads
• • POST /v1/transcodes — multi-input FFmpeg pipeline with a filters array
• • GET /v1/transcodes/:id — poll until completed
• • GET /v1/transcodes/:id/download — signed MP4 URL