Skip to main content
Glama

smovie

A small download service for YouTube and TikTok, built to run all the time on the Mac mini. You send it a URL, it adds a job to a queue (to run now, in turn, or at a set time), and yt-dlp downloads the video. You follow progress on a view-only dashboard, through the REST API, or through an MCP server that agents can use.

URL ──► POST /api/jobs ──► SQLite queue ──► worker (yt-dlp, N at a time) ──► data/downloads/<job>/
                               ▲                                              │
        dashboard (view) ──────┤                                              ▼
        MCP server (agents) ───┘                               GET /api/jobs/<id>/file

Run

uv sync
uv run smovie                 # http://localhost:8787  (dashboard)  /docs (API)

To install it on the mini so it starts at login and restarts if it crashes:

SM_API_TOKEN=change-me deploy/install-launchd.sh

Requires ffmpeg (brew install ffmpeg) to merge video and audio.

Settings (environment variables)

Var

Default

SM_DATA_DIR

./data (launchd: ~/smovie-data)

DB, downloads, log

SM_PORT

8787

SM_CONCURRENCY

2

parallel downloads

SM_API_TOKEN

none

if set, API needs Authorization: Bearer … (dashboard: open /?token=… once)

SM_COOKIES_FILE

none

Netscape cookies.txt, for YouTube "confirm you're not a bot" errors

SM_API_URL

http://127.0.0.1:8787

where the MCP server finds the API

Related MCP server: Importly MCP Server

API

Method

Path

POST

/api/jobs

{"url", "when": "now"|"queue"|"schedule", "run_at"?, "audio_only"?, "max_height"?, "purpose"?, "studio"?}

GET

/api/jobs?status=queued,downloading&limit=100

list jobs

GET

/api/jobs/{id}

status, progress, speed, eta, title, error

GET

/api/jobs/{id}/file

download the finished file

POST

/api/jobs/{id}/cancel

cancel a scheduled, queued or running job

POST

/api/jobs/{id}/retry

requeue a failed or canceled job

DELETE

/api/jobs/{id}?delete_file=true

remove job (and its file)

GET

/api/stats, /api/health

when=now moves the job to the front of the queue (it still waits if all download slots are busy). run_at without a timezone means the mini's local time.

curl -X POST localhost:8787/api/jobs -H 'content-type: application/json' \
  -d '{"url":"https://www.tiktok.com/@user/video/123","when":"schedule","run_at":"2026-10-29T02:00"}'
curl -OJ localhost:8787/api/jobs/<id>/file

Jobs that were downloading when the service stopped go back to the queue when it restarts.

Animation Studio (codex-3d)

"purpose": "depth" (or "action") on a job hands the finished file to Animation Studio, which polls for done jobs once a minute and takes each in once (hardlinked, so deleting the job keeps its copy). "studio" carries its fields: id, name, rights, and optionally window [start, end] in seconds with scene, for a depth reference of that window. Depth and action downloads are video, capped at 1080.

curl -X POST localhost:8787/api/jobs -H 'content-type: application/json' \
  -d '{"url":"https://youtu.be/…","purpose":"depth","studio":{"id":"got-olenna","name":"Olenna","rights":"non-commercial reference"}}'

Agents

  • MCP: .mcp.json registers smovie-mcp (stdio). The tools are submit_video, wait_for_job, save_video, list_jobs, get_job, cancel_job, retry_job and delete_job. To use it from another machine, set SM_API_URL=http://<mini>.local:8787 (and SM_API_TOKEN).

  • Skill: .claude/skills/video-download/SKILL.md covers the same flow with curl.

Maintenance

YouTube and TikTok change often, so keep yt-dlp up to date. Running deploy/update-ytdlp.sh weekly is enough.

Roadmap

  • Trimming: add trim: {start, end} to the job options and run ffmpeg -ss … -to … -c copy after the download.

  • Cloud: the same service in a container. Expect YouTube to block datacenter IPs, so plan on cookies or a residential proxy.

License

MIT, see LICENSE. Only download content you have the right to; downloading may break YouTube's and TikTok's terms of service.

Available Tools

8 tools
cancel_jobC

Cancel a scheduled, queued or running job.

Inputs: job_id (required).

delete_jobB

Remove a job from the list, and its file from the server unless delete_file is false.

Inputs: job_id (required), delete_file.

get_jobC

Get one job: status, progress %, speed, title, filename, error.

Inputs: job_id (required).

list_jobsA

List recent jobs, newest first. status filters by comma-separated states: scheduled, queued, downloading, done, failed, canceled.

Inputs: limit, status.

retry_jobA

Put a failed or canceled job back in the queue.

Inputs: job_id (required).

save_videoB

Copy a finished job's file from the service to a local folder. Returns the saved path.

Inputs: job_id (required), dest_dir.

submit_videoA

Add a YouTube or TikTok URL to the download queue.

when: "now" jumps the queue, "queue" waits its turn, "schedule" starts at run_at
(ISO 8601, e.g. "2026-10-29T02:00"; no timezone = the server's local time).
max_height caps resolution (e.g. 1080). Returns the job, including its id.
purpose: "depth" (or "action") hands the finished file to Animation Studio (codex-3d), which picks up
done jobs by itself; studio carries its fields: id, name, rights, and optionally window [start, end]
in seconds and scene (then a depth reference is made for that window).

Inputs: url (required), when, run_at, studio, +3 more.

wait_for_jobC

Wait until a job is done, failed or canceled (or the timeout passes) and return it.

Inputs: job_id (required), timeout_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct role across the job lifecycle: submit, inspect, list, wait, save, cancel, retry, and delete. The nearest pair, get_job and wait_for_job, is differentiated by wait_for_job blocking until a terminal state or timeout.

    Naming Consistency5/5

    All eight tools follow a consistent snake_case verb_noun pattern (get_job, submit_video, list_jobs, wait_for_job, save_video, cancel_job, retry_job, delete_job). No mixed casing or inconsistent verb styles appear.

    Tool Count5/5

    Eight tools is well-scoped for a video download queue service, covering submission, monitoring, waiting, file retrieval, and lifecycle management without bloat. Each tool earns its place in the workflow.

    Completeness5/5

    The surface covers the full job lifecycle: create/submit, get, list, wait, save finished files, cancel, retry, and delete. Scheduling and Animation Studio handoff are handled through submit_video, leaving no obvious dead ends for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers