picodevil-server

Hello! This is a server to help use custom videos in picodevil.

It's useful for doing things like:

• downloading videos from YouTube
• transcoding videos so they have every frame as an I-frame (useful for skipping about or playing them backwards, both of which picodevil encourages you to do)
• also just hosting custom videos without putting them online

Install & run

Unfortunately, it's currently only a command-line thing. It runs in Node, so you'll need that and npm installed. If you don't know what those are, or aren't sure if they're on your computer — sorry! I do want to make a version wrapped up in a GUI, but I haven't for now.

If you do, then run these commands from the command line:

git clone https://github.com/v21/picodevil-server.git
cd picodevil-server
npm install
npm start

This should download yt-dlp and then show you something like:

> picodevil-server@1.0.0 start
> node server.js
Using yt-dlp: /Users/v/picodevil/server/bin/yt-dlp
Using ffmpeg: /Users/v/picodevil/server/node_modules/ffmpeg-static/ffmpeg
picodevil-server running on http://localhost:47426
Endpoints:
GET /health — identity probe, returns {name, version, apiVersion, port, ok}
GET /url?v=YOUTUBE_URL — get direct MP4 URL (expires, IP-locked)
GET /download?v=YOUTUBE_URL — download video locally, returns serve path
POST /upload?name=foo.mp4 — upload a local file, re-encode as I-frame-only MP4
GET /videos/<id>.mp4 — serve a video (supports range requests; streams while transcoding)
GET /images/<file> — serve a cached image (png/jpg/gif/webp)
GET /ready/<stem> — check if a transcoding job is complete
yt-dlp version: 2026.03.17

You'll then want to tell picodevil where to find the server. Open the videos tab in the sidebar, click the little server status button at the bottom, and paste in http://localhost:47426 (or whatever npm start gives you). The little status icon should turn green.

Okay, what can I do with it?

You should now be able to:

• paste a YouTube URL into the textbox at the top of the videos tab - it'll download it from YouTube, then transcode it
• drag a local file onto the videos tab. It'll copy it to the videos subfolder and transcode it

(transcoding takes a while, so you might have to be patient!)

You can also run the script as a CLI to add videos: node server.js download "https://www.youtube.com/watch?v=FNpEwnofQcs"

or, if there are videos you've manually added by dragging into the videos subfolder, you can transcode them: node server.js transcode all

node server.js help will show you the help reference.

Technical bits

There are some config options:

Env var / flag	Default	Effect
PICODEVIL_PORT (env) or --port N	47426	Port the server binds to. Also accepts --port=N.
PICODEVIL_CORS_ORIGIN	(built-in allowlist)	Comma-separated origins allowed to connect, or * to allow any origin.

The built-in CORS allowlist allows the server to be accessed from:

• http://localhost:* and http://127.0.0.1:* (any port — for local dev)
• https://picodevil.com and https://*.picodevil.com (production + subdomains)

To allow a custom URL to access the server, run it by passing PICODEVIL_CORS_ORIGIN, like so:

PICODEVIL_CORS_ORIGIN=https://my-fork.example.com npm start

License info

This is licensed under the AGPL license! You can modify it as you wish, but if you make those changes public you gotta share them back!