Sniplette

Sniplette is a tiny video helper that turns large social media videos into small, shareable clips. Give it a link from Instagram, YouTube, Threads, Facebook, TikTok, or Twitter, and Sniplette will fetch → transcode → compress → and hand you a neat little "snip" perfect for messaging apps, chats, and social platforms.

✨ Features

• 📥 Downloads from Instagram, YouTube, Threads, Facebook, TikTok, and Twitter
• 🎞️ Re-encodes with ffmpeg for consistent, mobile-friendly formats
• 📦 Shrinks videos down to configurable size limits (e.g., 50 MB)
• 📱 Ensures compatibility with messaging apps like WhatsApp, Telegram, and iMessage
• 🖼️ Outputs clean MP4/H.264 (yuv420p) or lightweight audio/video variants
• 🛠️ Simple, compact Go CLI

This tool does not bypass authentication or DRM; it only works with publicly accessible URLs.

Supported Platforms

Platform	Domains	Backend
Instagram	instagram.com, instagr.am	yt-dlp
YouTube	youtube.com, youtu.be	yt-dlp
Threads	threads.net	lux
Facebook	facebook.com, fb.watch	lux
TikTok	tiktok.com	yt-dlp (lux fallback)
Twitter/X	twitter.com, x.com	yt-dlp (lux fallback)

Authentication

Some Instagram content (Stories, private posts) requires authentication. Sniplette supports importing cookies from your browser via yt-dlp's cookie extraction.

Usage

# Use cookies from Brave browser
sniplette --cookies-from-browser brave https://www.instagram.com/stories/username/id/

# Use cookies from other browsers
sniplette --cookies-from-browser chrome:Default https://...
sniplette --cookies-from-browser firefox https://...
sniplette --cookies-from-browser safari https://...

Supported browsers

brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale

For Chromium-based browsers with multiple profiles, specify the profile name:

--cookies-from-browser "chrome:Profile 1"
--cookies-from-browser "brave:Default"

How it works

• Sniplette passes --cookies-from-browser to yt-dlp
• yt-dlp reads cookies from your browser's database on disk
• The browser does not need to be running
• Cookies are decrypted using your OS keychain (macOS) or keyring (Linux)
• Sniplette never reads or stores cookies itself

Configuration

You can set a default browser in your config file or environment:

# ~/.config/sniplette/config.yaml
cookies_from_browser: "brave"

export SNIPLETTE_COOKIES_FROM_BROWSER="brave"

When authentication is required

If you try to download content that requires login without providing cookies, Sniplette will show a helpful error:

Instagram requires authentication. Re-run with --cookies-from-browser brave (or chrome:Default, firefox, safari)

Requirements

• Go 1.23+
• External tools in your PATH:
  • yt-dlp (preferred) or youtube-dl
  • ffmpeg
• lux is bundled as a Go library (no separate install needed)

Sniplette detects tools at startup:

1. If --dl-binary is provided, it uses that path/name.
2. Else SNIPLETTE_DL_BINARY env var (with compatibility fallback to IG2WA_DL_BINARY).
3. Else search yt-dlp, then youtube-dl.
4. It must also find ffmpeg, otherwise it exits with a helpful message.

Install Dependencies

Below are common ways to install yt-dlp and ffmpeg. Choose what fits your system best.

macOS (Homebrew)

brew install yt-dlp ffmpeg

Ubuntu/Debian

# ffmpeg from apt
sudo apt-get update
sudo apt-get install -y ffmpeg

# yt-dlp via pip (recommended)
python3 -m pip install --user -U yt-dlp
# Make sure pip's bin dir is in your PATH (often ~/.local/bin)

Alternatively (if your distro provides it):

sudo apt-get install -y yt-dlp

Arch Linux

sudo pacman -S yt-dlp ffmpeg

Other Distros

• Install ffmpeg with your package manager.
• Install yt-dlp with your package manager or via pip install -U yt-dlp.
• As a fallback, install youtube-dl if you can't use yt-dlp.

Build

From the repository root:

make build

This produces a sniplette binary in the ./bin directory.

To install into your $GOBIN:

make install

Configuration

Sniplette supports a configuration file and environment variables via Viper.

• Config formats: yaml, yml, json, toml (loaded as config.{yaml|yml|json|toml})
• Config search path:
  • Linux: $XDG_CONFIG_HOME/sniplette/config.{yaml|yml|json|toml} (default: ~/.config/sniplette/)
  • macOS: ~/Library/Application Support/sniplette/config.{yaml|yml|json|toml}
  • Windows: %AppData%/sniplette/config.{yaml|yml|json|toml}
• Environment variables:
  • Prefix: SNIPLETTE_
  • Hyphens in keys convert to underscores for env vars (e.g., out-dir → SNIPLETTE_OUT_DIR)
• Precedence:
  • CLI flags > environment variables > config file > defaults

Supported configuration keys (in config file and env):

• out_dir (or out-dir)
• verbose
• dl_binary (or dl-binary)
• jobs
• cookies_from_browser (or cookies-from-browser)

Example config.yaml:

# ~/.config/sniplette/config.yaml (Linux)
# ~/Library/Application Support/sniplette/config.yaml (macOS)
# %AppData%/sniplette/config.yaml (Windows)

out_dir: "/home/user/Videos/sniplette"
verbose: true
dl_binary: "yt-dlp"   # or a full path like /usr/local/bin/yt-dlp
jobs: 4

Environment variable examples:

export SNIPLETTE_OUT_DIR="$HOME/Videos/sniplette"
export SNIPLETTE_DL_BINARY="/usr/local/bin/yt-dlp"
export SNIPLETTE_JOBS=4
export SNIPLETTE_VERBOSE=true

Usage

Sniplette uses the Cobra framework with subcommands. You can run directly with a URL or use explicit subcommands:

# Direct run (no subcommand)
sniplette <url> [<url> ...] [flags]

# Run download/encode pipeline
sniplette run <url> [<url> ...] [flags]

# Show plan (metadata-only) without executing
sniplette plan <url> [<url> ...] [flags]

# Force TUI mode for interactive runs
sniplette tui <url> [<url> ...] [flags]

# Diagnose external dependencies
sniplette doctor

# Generate shell completion scripts
sniplette completion [bash|zsh|fish|powershell]

Commands

• run

  • Description: Execute the fetch/transcode pipeline for tiny, snack-sized snips.
  • Usage: sniplette run [urls...] [flags]

• plan

  • Description: Show a tiny plan (metadata-only) without running encoder or writing outputs.
  • Usage: sniplette plan [urls...] [flags]

• tui

  • Description: Force TUI mode for interactive snips (jobs, progress, etc.).
  • Usage: sniplette tui [urls...] [flags]
  • Notes: If stdout is not a terminal, this will error appropriately.

• doctor

  • Description: Diagnose external tools and show resolved paths.
  • Usage: sniplette doctor
  • Output example:

    Downloader: /usr/local/bin/yt-dlp
    FFmpeg:    /opt/homebrew/bin/ffmpeg
    

• completion

  • Description: Generate shell completion scripts.
  • Usage: sniplette completion [bash|zsh|fish|powershell]

Flags

Core flags (available for subcommands):

• -o, --out-dir string Output directory (default: .)
• --max-size-mb int Target max size per video in MB (default: 50; set 0 to use CRF/quality mode)
• --quality-preset string Preset quality: low, medium, high (default: medium)
• --resolution int Override long-side resolution in px (e.g., 540, 720, 1080)
• --audio-only Extract audio only (M4A)
• --caption string Caption output: txt, none (default: txt)
• --keep-temp Keep intermediate download files
• --dl-binary string Path or name for yt-dlp/youtube-dl
• --cookies-from-browser string Import cookies from browser (e.g., brave, chrome:Default, firefox)
• --no-fallback Disable lux fallback for TikTok/Twitter (use yt-dlp only)
• -v, --verbose Show full subprocess commands/output
• --jobs int Max concurrent jobs in TUI (default: 2)

Quality presets mapping:

• low: 540p, max-size-mb=20, crf=26
• medium (default): 720p, max-size-mb=50, crf=22
• high: 1080p, max-size-mb=100, crf=19

Examples

Subcommand syntax:

# Explicit run
sniplette run https://www.instagram.com/reel/ABC123/

# Plan
sniplette plan -v https://www.instagram.com/reel/ABC123/

# Force TUI
sniplette tui --jobs 4 https://www.instagram.com/reel/ABC123/ https://youtu.be/BBB

# Dependency check
sniplette doctor

# Generate shell completion for zsh (see below to load)
sniplette completion zsh

Shell Completion

Load completions for your current shell:

• Bash:

  source <(sniplette completion bash)

• Zsh:

  sniplette completion zsh > "${fpath[1]}/_sniplette"

• Fish:

  sniplette completion fish | source

• PowerShell:

  sniplette completion powershell | Out-String | Invoke-Expression

You can persist these according to your shell's standard initialization configuration.

Output Details

• Video container: MP4
• Video codec: H.264 (libx264), yuv420p pixel format, -preset veryfast, profile main
• Audio codec: AAC at 96 kbps (configurable in code)
• Scaling:
  • Vertical (height > width): scale=-2:LONG_SIDE
  • Horizontal: scale=LONG_SIDE:-2
• Size/quality modes:
  • Size-constrained (default): Computes bitrate from duration and --max-size-mb for compact results.
  • CRF mode: Use --max-size-mb 0 to switch to quality-based CRF encoding (preset CRFs: low=26, medium=22, high=19).

Captions:

• By default, the original caption is written to a .txt file next to the snip.
• Disable with --caption none.

Exit Codes

• 0 success
• 1 invalid usage or CLI error
• 2 missing dependency (yt-dlp/youtube-dl or ffmpeg)
• 3 download error
• 4 transcode error

Hybrid Backend Architecture

Sniplette uses a hybrid approach to maximize platform coverage:

• yt-dlp primary: Instagram and YouTube use yt-dlp exclusively for reliable extraction
• lux primary: Threads and Facebook use lux since yt-dlp lacks extractors for these platforms
• Fallback mode: TikTok and Twitter try yt-dlp first, falling back to lux on failure

Use --no-fallback to disable lux fallback for TikTok/Twitter if you prefer yt-dlp-only behavior.

Troubleshooting

• "Could not find yt-dlp or youtube-dl": Install yt-dlp and ensure it's in PATH, or pass --dl-binary.
• "Could not find ffmpeg": Install ffmpeg and ensure it's in PATH.
• Size slightly exceeds target: The bitrate calculation is approximate. Consider increasing --max-size-mb, lowering resolution, or switching to CRF mode.
• Non-ASCII titles/usernames: Filenames are sanitized and truncated to safe, UTF‑8‑preserving names.

Build From Source (Recap)

# From repo root
go build ./cmd/sniplette

# Run
./sniplette --help

Legal/Ethical Note

This tool should only be used to download videos you're allowed to (your own content, or with permission). You must comply with Instagram's Terms of Service and local copyright laws. This tool orchestrates yt-dlp/ffmpeg and does not bypass DRM. When using --cookies-from-browser, you are accessing content with your own authenticated session.

Acknowledgments

• yt-dlp - Primary video extraction for Instagram/YouTube
• lux - Video extraction library for Threads/Facebook support
• ffmpeg - Media transcoding
• Bubble Tea - Terminal UI framework

License

MIT License - Copyright © 2025