Local-first macOS media workbench powered by yt-dlp and ffmpeg. Use the CLI or localhost interface to:
- Download permitted public video and audio.
- Fetch public captions or create timed text locally with
whisper.cpp. - Convert local video, audio, and image files.
- Cut exact ranges or find clip highlights from timestamped text with optional Gemini BYOK analysis.
Media stays on your Mac. Gemini receives text only after an explicit action; video and audio are never uploaded by dlmac.
- macOS
- Homebrew
- yt-dlp
- ffmpeg
- webp (provides the
cwebpandgif2webpencoders) - Optional: whisper-cpp (provides local speech-to-text)
- Go 1.26 or newer to build the optional local web interface
git clone https://github.com/srmdn/dlmac.git
cd dlmac
./install.shinstall.sh checks dependencies, offers to install missing ones via Homebrew,
and builds the dlmac-web helper next to the CLI.
To run dlmac from any directory, add the project directory to your PATH or
copy both dlmac and dlmac-web to a directory that is already in your
PATH, such as ~/.local/bin.
The compiled web helper does not require Go or the project source tree at
runtime. Keep dlmac and dlmac-web in the same directory.
dlmac info <url> Show video metadata
dlmac formats <url> Show available formats
dlmac video <url> Download best video (mp4)
dlmac video <url> --quality 360p Download best video up to 360p
dlmac video <url> --quality 480p Download best video up to 480p
dlmac video <url> --quality 720p Download best video up to 720p
dlmac video <url> --quality 1080p Download best video up to 1080p
dlmac audio <url> Download best audio (mp3)
dlmac audio <url> --format mp3 Download audio as mp3
dlmac audio <url> --format m4a Download audio as m4a
dlmac audio <url> --format wav Download audio as wav
dlmac transcript <url> Download transcript as txt (English)
dlmac transcript <url> --lang id Download Indonesian transcript
dlmac transcript <url> --lang en Download English transcript
dlmac transcript <url> --format txt Download transcript as plain text
dlmac transcript <url> --format vtt Download transcript as WebVTT
dlmac transcript <url> --format srt Download transcript as SRT
dlmac transcribe <file> Create timed text from local media
dlmac transcribe <file> --lang id --model /path/to/ggml-small.bin
Use Indonesian and a specific local model
dlmac serve Start localhost web UI
dlmac ui Alias for serve
dlmac convert <file> --to <format> Convert local video, audio, or image media
dlmac clip <file> --start <time> --end <time>
Cut a local video segment to an MP4 clip
dlmac clip <file> --start <time> --end <time> --format vertical --layout blur
Render a vertical clip with blurred fill
Public YouTube video downloads retry HTTP 403 responses with the
web_embedded client and a compatible progressive format when needed. The
localhost Download page uses the same video engine and preserves retry output
in Technical details.
Outputs stay under ./downloads/, grouped by workflow:
- Online video downloads:
./downloads/video/ - Online audio downloads:
./downloads/audio/ - Transcripts:
./downloads/transcripts/ - Local conversions:
./downloads/converted/ - Video clips:
./downloads/clips/
Existing files directly inside ./downloads/ remain supported and are not
moved automatically.
# Get video info
./dlmac info "https://example.com/video"
# Download video at 720p
./dlmac video "https://example.com/video" --quality 720p
# Download audio as mp3
./dlmac audio "https://example.com/video" --format mp3
# Download Indonesian transcript as plain text
./dlmac transcript "https://example.com/video" --lang id
# Run globally if dlmac is installed in PATH
dlmac transcript "https://example.com/video" --lang en --format txt
# Start the local web interface
./dlmac serve
# Create a timed local transcript for Clipper
./dlmac transcribe recording.mp4 --format vtt --model /path/to/ggml-small.bin
# Convert a local video to a QuickTime-compatible MP4
./dlmac convert myvideo.webm --to mp4
# Extract audio from a local video
./dlmac convert myvideo.mp4 --to mp3
# Convert a local image
./dlmac convert artwork.png --to tiff
# Convert a local image to WebP
./dlmac convert artwork.png --to webp
# Convert a local audio file
./dlmac convert recording.wav --to flac
# Cut a local video segment
./dlmac clip recording.mp4 --start 00:01:30 --end 00:02:15The local interface opens the transcript page first. Use the shared sidebar to
navigate between dedicated Transcript, Download, Convert, and Clipper pages.
Each page keeps its controls and contextual result area separate. Long-running
work continues as a local background job when you navigate, and each page
restores its current job plus lightweight recent history. New job clears
the current workspace view without deleting saved artifacts. The history
remove action deletes only the selected job record; saved output stays in
downloads/.
The Download page uses the same dlmac video engine as the CLI. Public YouTube
video requests that receive HTTP 403 are retried with web_embedded and a
compatible progressive format, and the UI keeps the retry output in Technical
Technical details.
dlmac clip <file> --start <time> --end <time> cuts one local video segment
with FFmpeg and saves a QuickTime-compatible MP4 in ./downloads/clips/.
Times accept seconds, MM:SS, or HH:MM:SS. Existing clip files are never
overwritten.
The CLI also accepts --format original|vertical|square. Vertical output can
use --layout crop|blur; other formats use a centered crop where applicable.
The local web workbench preserves manual clipping and adds an optional
transcript-assisted flow. Reuse a timed WebVTT or SRT artifact, import a
matching caption file, or create timed text from the selected local video with
whisper.cpp. Opening Transcript from Clipper preselects WebVTT and offers the
saved timed transcript back to the Clipper draft.
Explicitly consent to sending its text and timestamps to Gemini, review and
edit the suggested ranges, then render only the selected clips. Video and
audio bytes remain on this Mac.
Local transcription requires a multilingual GGML model. Download one from the
official whisper.cpp model collection,
then select the .bin file in Clipper. You can also set
DLMAC_WHISPER_MODEL to reuse the same model automatically. The recommended
small model uses about 466 MiB of disk space. Model files stay outside the
repository. dlmac uses CPU-only inference by default for compatibility. Set
DLMAC_WHISPER_GPU=1 to try the accelerated backend; dlmac retries on CPU if
acceleration fails.
The local web workbench includes an opt-in Gemini BYOK integration. It keeps
yt-dlp as the transcript engine and uses Gemini only when you explicitly ask
for analysis.
Open Settings in the sidebar to enter your Gemini API key and model. The
default model is gemini-3.6-flash. The key is stored in a machine-local
settings file with owner-only permissions, and the UI never displays it after
you save it. You can also configure a key through the environment:
export GEMINI_API_KEY="your-key"GOOGLE_API_KEY takes precedence when both environment variables are set.
Use Test connection in Settings before requesting a summary. The
summary action follows the selected caption language, sends transcript text
only, saves the result as a Markdown artifact beside the transcript, and never
uploads the source video, audio, or image. Clipper suggestions use the same key
but send timestamped caption text only after explicit consent.
dlmac convert <file> --to <format> accepts one local media file and saves the
result in ./downloads/converted/ without overwriting an existing file.
Supported target formats are:
- Video:
mp4,webm,mkv, andmov. - Audio:
mp3,m4a,wav,flac,ogg, andopus. - Images:
jpg,png,gif,tiff, andwebp.
Video targets re-encode when needed. The mkv target can preserve compatible
streams without re-encoding. Audio targets remove the video stream, and image
targets export the first video frame when the input contains video.
The local web workbench provides a native macOS file picker. It sends only the selected path to the localhost server; it does not upload the media file to a remote service. Results are local artifacts with contextual preview, copy, and Show in Finder actions; the UI does not create a redundant browser download.
WebP output uses the official cwebp encoder from the Homebrew webp
package. Animated GIF input uses the companion gif2webp encoder. The local
web workbench shows the WebP target only when those tools are available.
Video downloads produce H.264 video with AAC audio in an MP4 container. This is the format QuickTime, Safari, and Apple's media framework expect.
If the source offers H.264+AAC natively, dlmac downloads it directly with zero re-encoding — fast and lossless. If H.264+AAC is unavailable, dlmac automatically re-encodes the output with ffmpeg.
Players like VLC, IINA, and mpv can play any codec combination. The H.264+AAC preference only matters for QuickTime and Apple apps.
QuickTime can't open the file
The output is already H.264+AAC and should work with QuickTime. If you
still have issues, check that ffmpeg is installed (brew install ffmpeg)
and that your yt-dlp is up to date (brew upgrade yt-dlp).
YouTube returns "HTTP Error 403: Forbidden"
For public YouTube video downloads, dlmac retries a 403 with YouTube's
web_embedded client. It first tries the requested H.264+AAC quality and then
tries the best progressive format at or below the requested quality if the
split format is also rejected. web_embedded only works for videos that allow
embedding, and it may produce a lower resolution when that is the best
available public format. dlmac does not use cookies or login sessions.
No H.264 formats available Some videos (particularly at 1080p and above) only offer VP9/AV1 video. dlmac falls back to whatever is available and re-encodes automatically. You'll see a "Re-encoding to H.264+AAC" message during download.
"Re-encoding to H.264+AAC" message appears This is normal when the source doesn't provide H.264+AAC natively. The download will take longer because ffmpeg must re-encode the entire video. The result is still a QuickTime-compatible MP4.
"web helper not found" message appears
Run ./install.sh from the project checkout to build dlmac-web. If you copy
the CLI to another directory, copy dlmac-web with it.
WebP output is unavailable
Install the official WebP tools with brew install webp, then run
./install.sh again. The local web interface hides WebP when cwebp or
gif2webp is unavailable.
Local transcription is unavailable
Install the engine with brew install whisper-cpp. Download a multilingual
GGML model separately, then select it in Clipper or set
DLMAC_WHISPER_MODEL=/absolute/path/to/model.bin.
- macOS only
- No playlist support
- No interactive format selector in the CLI; the local web workbench provides a curated format selector
- AI clip suggestions require timestamped VTT or SRT text. dlmac can create it
locally with
whisper.cpp, but it does not provide scene or face tracking - Gemini analysis remains optional and explicit for transcript summaries and transcript-assisted clip suggestions
- No login/cookie support
- Transcript support depends on public captions or auto captions being available for the selected language
- Building the local web interface requires Go 1.26 or newer
- Quality depends on source video availability; falls back to best available below the requested resolution
dlmac is a general-purpose media downloader built on yt-dlp. It does not discriminate by platform — any URL yt-dlp supports will work. However, not all platforms permit downloading.
You are responsible for:
- Ensuring you have the right to download the content
- Checking each platform's terms of service before downloading
- Respecting copyright, licensing, and applicable laws in your jurisdiction
What dlmac does NOT do:
- Bypass DRM, paywalls, or access restrictions
- Store or transmit login credentials (no cookie/auth support)
- Access private, unlisted, or members-only content
- Circumvent platform rate limits or anti-bot measures
Platform policies vary. Each platform has its own terms of service regarding downloads. Check the relevant policies before downloading. dlmac does not encourage violating any platform's policies — it simply passes your URL to yt-dlp. The choice of what to download is yours, and so is the responsibility.
If you are unsure whether downloading specific content is legal in your country or permitted by the platform, consult a legal professional.
GPL-3.0-or-later