Posts

Videos

A video post is a post like any other: it has an audience, replies, likes, a place in feeds. What is different is how it gets there. A video is too big to be sent to the API, and nothing somebody uploads is ever shown as it arrived, so a browser sends the file straight to storage, a worker makes the files that are shown, and only then is there a post.

Its routes are in the API reference: video-service.

The parts

Part What it does
video-service (port 8103, /videos/) Begins and finishes uploads, says how each is getting on, and serves video posts: read, edit, delete, audience, replies, pin. Sends viewers to a video's files
video-worker Takes each finished upload, checks it, makes its sizes and poster with ffmpeg, stores them, and makes the post. Answers no requests
file-grpc-service Signs the addresses the browser sends parts to and the worker reads and writes at, and holds each to its place in storage
video_uploads One row for each upload: the post as it will be, where the file is, how far it has got, and how many times it has been tried

The two video containers are one module, video-service, with two programs (cmd/api, cmd/worker) and two images. The worker's image has ffmpeg in it and runs as a user of its own.

Sending a video

  1. POST /videos/:owner_id/uploads with what the post will say (title, content, access, language, reply_access, quote_policy) and the file's size and content_type. Everything about the post is settled now, by the rules for any post: whether this person may post on that profile, and to that audience. The answer has the upload's id, a part_size (8 MB) and a part_count.
  2. POST /videos/uploads/:id/parts { "numbers": [1, 2, 3] } answers with an address for each part. The browser PUTs each part to its address, in any order, again if one fails. Addresses are asked for a few at a time and are good for an hour.
  3. POST /videos/uploads/:id/complete makes one file of the parts. How much arrived is asked of storage, not of the browser: a file past the limit is thrown away whatever size was given in step 1.
  4. GET /videos/uploads/:id says how it is getting on: uploading, processing, ready with the post's node_id, or failed with why.

An upload can be given up at any point (DELETE /videos/uploads/:id). One that is begun and never finished is thrown away after 24 hours.

There is no post until step 4 says ready. Nothing has to be hidden from feeds in the meantime, and an upload that goes nowhere leaves nothing behind.

What the worker does

For each upload that is all there, one at a time:

  1. Reads the file from storage, stopping at the largest a video may be.
  2. Decides what it is; see below.
  3. Makes each size, never larger than the video is: H.264 and AAC in an MP4 arranged so that it starts playing before all of it has arrived.
  4. Makes the poster, a JPEG of a frame one second in.
  5. Stores them under assets/v1/video-service/videos/<profile id>/<upload id>/.
  6. Makes the post, as the person who uploaded it, and marks the upload ready.
  7. Deletes the upload.

Several workers can run at once: each takes a different upload (SELECT … FOR UPDATE SKIP LOCKED). A worker that dies leaves its upload taken; another takes it once the first must be dead, which is after longer than the work on one video is allowed to last. That allowance grows with the longest video allowed and the sizes made.

What went wrong What happens
The file is not a video (not_a_video), or is too long (too_long), or too large (too_large), or is a GIF or PNG that does not move (still) failed, for good, and the upload is deleted
Anything else: storage, the network, ffmpeg itself Tried again, up to 3 times, then failed as encoding
The uploader gave it up meanwhile What was made is deleted, and no post is made

What a file has to be

The file is a stranger's and nothing has looked at it.

  1. Its first bytes say what it is, and only these kinds are taken: MP4 or QuickTime (an ftyp box), WebM or Matroska (EBML), and the two moving pictures, GIF (GIF87a or GIF89a) and animated PNG (a PNG that says how it moves, acTL, before its picture begins). This is read before ffmpeg is given the file. ffmpeg opens many kinds of file, and some of them are lists of other files to read and addresses to fetch.
  2. ffmpeg is told which kind it is given (-f), so it never guesses, and may open files and nothing else (-protocol_whitelist file).
  3. It must have a picture: sound alone, or a song with its cover, is not a video.
  4. It must be no longer than VIDEO_MAX_SECONDS, or, for a GIF or an animated PNG, ANIMATION_MAX_SECONDS.
  5. ffmpeg is run with nothing of the worker's environment but PATH.

Nothing of the upload is kept. Every file shown is encoded afresh with no metadata copied over, so a title, a location or anything else written into the upload stays in the upload, which is deleted.

What the browser says the file is (content_type) only turns away what could never be a video. It decides nothing.

The post

A video post is a node of type node.medium.video-service.video.v1 (an audio post, node.medium.video-service.audio.v1: Audio posts). Its files are described in its meta under video: the duration, each size with its key in storage, and the poster. Nothing but the worker writes that, and anahita-libs/videos is the one place that reads it.

Wherever a post is sent, a video post has:

"video": {
  "duration": 61.5,
  "width": 1920,
  "height": 1080,
  "poster": "/videos/170301/files/poster.jpg",
  "files": [
    { "height": 1080, "width": 1920, "url": "/videos/170301/files/1080.mp4", "type": "video/mp4" },
    { "height": 720,  "width": 1280, "url": "/videos/170301/files/720.mp4",  "type": "video/mp4" },
    { "height": 360,  "width": 640,  "url": "/videos/170301/files/360.mp4",  "type": "video/mp4" }
  ]
}

It is in feeds, search and custom feeds (kind video) like any post, and the web shell describes a public one at /videos/<id>.

Deleting the post deletes its files. So does purging the account that posted it.

In a thread

A thread written in one go (roadmap row 143) can have a GIF, a video or a sound in any note. Its notes before the first file are made at once (POST /notes/…/thread); each file is an upload, and the notes after it wait with it until it is ready:

  1. thread_after on POST /videos/:owner_id/uploads: the notes after this one up to the next file, as a thread's parts, up to nine, checked when the upload begins (each says something; its pictures are the writer's). Kept in video_uploads.thread_after.
  2. after_upload: the writer's own upload before this one in the same thread. This one is a reply, on the writer's own profile, and is not taken by a worker until that one's post and notes are made, when it is let go to answer the last of them (video_uploads.after_upload_id).
  3. The worker makes the post, then its notes in one go, each a reply to the one before, with the thread's content warning; their links are not made into cards, which only text-service makes. The upload is ready once all are made.
  4. A failure stops the thread there. An upload whose upload before it failed or was given up fails as thread_stopped; notes that cannot be made (a picture in them gone) fail the file too, as thread_notes, and its post is taken back. Notes and files before it stay.

The writer may leave the page once every file is sent, as with any video.

Playing it

The addresses in video are paths under the API that stay the same. Each is answered with a redirect to a signed address in storage, where the file is read in ranges as a player asks.

Who may see the post is asked every time one of those paths is followed. A file is never reached by somebody who may not see the post, and an address does not go on working after the post is made private or deleted. A player sends the viewer's session cookie with the request, as a browser does for any picture or video on a page.

The signed address lasts 15 minutes. A player that asks for a new range after that, on a video left paused, follows the path again.

Sizes

VIDEO_RENDITIONS lists the sizes made, by height: 1080,720,360 unless said. Up to 2160 is taken, which is 4K. A video is never made larger than it is: one filmed at 720p has a 720p and a 360p file and no 1080p. One smaller than every size listed is made once, at its own size.

GIFs and animated PNGs

A GIF or an animated PNG is posted from the video composer, as Mastodon does with a GIF: it becomes a short clip with no sound that plays on a loop. It is a video post in every other way: who may see it, replies, likes, downloading and deleting are the same.

  1. It is held to less than a video: ANIMATION_MAX_BYTES (25 MB) and ANIMATION_MAX_SECONDS (30), never more than a video's own limits. Beginning an upload checks the size it says, and the worker checks what the file really is and its real size again.
  2. A picture that does not move is refused with the reason still, which the web app turns into "post it as a photo". A GIF of one picture is one; so is a PNG with no acTL, which the worker reads from the file's chunks, since ffmpeg's reader of animated PNGs will not open it. A picture less than ten pixels high or wide is refused as not a video.
  3. It is made once, at its own size up to 720 high, in numbers that divide by two: H.264 with no sound, each picture shown for as long as it was (-fps_mode passthrough), and +faststart. A clip is a fraction of the GIF's size: a two-second test GIF of 100 KB came to 16 KB.
  4. What was see-through is laid on white, since an MP4 and a JPEG have nothing see-through. That matters for stickers and not for the usual clip.
  5. Its poster is its first picture, on white.
  6. The post says it loops: "loop": true in video, in its meta and wherever it is sent. The web app plays it muted, on a loop, without controls, and still where the reader asked for less motion.

An animated WebP is not taken: ffmpeg 8.1, in the worker's image, reads the file but not its pictures. A WebP is refused as not a video.

More and larger sizes cost in three places, and the settings go together:

To allow Also raise
4K (VIDEO_RENDITIONS=2160,1080,720,360) VIDEO_MAX_BYTES: ten minutes of 4K is several gigabytes. And give the worker processor: 4K takes about nine times as long to encode as 720p
Longer videos (VIDEO_MAX_SECONDS) VIDEO_MAX_BYTES, and the worker's working space

The player chooses between the sizes a video has. Nothing changes size while it plays: that needs a different way of storing video (HLS), which is not built.

Downloading

As for a photo, and by the same rules: see Photo posts.

  • Whether a video may be downloaded is chosen when its upload begins (allow_download, or what the profile says when it is left out) and is carried to the post when the worker makes it. It is changed afterwards with PATCH /videos/:id/download.
  • GET /videos/:id/download saves the largest size the video has, and ?size=720 another. What is downloaded is what the worker made: the upload itself was deleted.

Audio posts

A sound is a post of its own kind, node.medium.video-service.audio.v1, made and kept by video-service, which has the worker and ffmpeg (roadmap row 137, Audio and video from everywhere (opens in a new tab)). It is posted where videos may be (VIDEO_UPLOADS), unless AUDIO_UPLOADS is off, and recorded in the composer only where AUDIO_RECORDING is on: the same two containers make it.

  1. Sent as a video is, in parts straight to storage, through the same routes, chosen as a file or recorded in the web app's composer, which records M4A or WebM as the browser does. What the browser says the file is decides: MP3, M4A and AAC, Ogg and Opus, WAV, FLAC and WebM sound make an audio post; the upload keeps its kind (video_uploads.kind). Held to AUDIO_MAX_BYTES and AUDIO_MAX_SECONDS (500 MB and an hour unless said), and to VIDEO_DAILY_UPLOADS with videos.
  2. The worker reads the file by its first bytes, as it reads a video, wants a sound in it, and keeps one file, AAC at 128 kbit/s in an M4A (audio.m4a), made to start at once, with nothing else of the file. The picture a file carries, an album's cover, becomes its cover (cover.jpg); a file with none has no cover.
  3. The post has a title, words and the rest as a video post has; its meta holds audio: how long it plays, its file, and its cover. The API sends it as audio: { duration, url, type, cover }, at /videos/:id/files/audio.m4a and cover.jpg, answered as a video's files are. A profile's audio posts are GET /videos/:owner_id/?type=audio, under an Audio tab.
  4. Downloaded as a video is, its M4A, where downloading is allowed.
  5. To the fediverse as a note with Mastodon's Audio attachment, its cover as its icon, its title first; to Bluesky, which has no sound, as its title and opening with a card that leads to it here, its cover the card's picture (Federation).
  6. Kept and removed as a video's files are: named for the nightly file sweep, removed with the post, with its profile, and in the download.

Videos from other networks

A post from Bluesky or the fediverse that carries a video is kept with its poster as its picture, and says where the video is (media_elsewhere in its meta: its kind, the file's address, its page and its site), roadmap row 120 (Audio and video from everywhere (opens in a new tab)). The video is copied here the first time somebody presses play, and played from this site's storage, never from its own server, which would tell that server who watched.

  1. Pressing play, somebody signed in asks for it (POST /videos/elsewhere/:id); the web app says "Getting the video…" and asks after it (GET) every two seconds. Somebody signed out is led to its page there.
  2. The worker fetches it, from public addresses only and not from a server this site refuses, at most REMOTE_MEDIA_MAX_BYTES and REMOTE_MEDIA_MAX_SECONDS, and keeps one file, at 720 or its own height when smaller. An MP4 that already plays everywhere (H.264 in 4:2:0, AAC or no sound, 720 or less) is kept as it is, made to start at once, not encoded again; any other is encoded once. A Bluesky video is read from its author's own server (getBlob), as it was posted. Tried on dev with a two-minute video of 48 MB at 1440 by 2560: copied, made 720 tall and playing in ten seconds, 9.8 MB kept.
  3. The copy goes into the post as a video posted here is (video in the API), and plays the same way; the post's picture is its poster.
  4. Kept for REMOTE_VIDEO_DAYS after it was last played, seven unless said, then removed, and copied again when played again.
  5. When it cannot be had (gone from its server, too large or too long, not a video, on a server refused here), the post says so and leads to its page. A file too large or too long is not tried again; one gone or failed for something here is, when play is pressed again.
  6. A post marked as not to be shown plainly keeps none of it, until content warnings (roadmap row 122) can put it behind one.

The queue is table media_elsewhere, one row for each post, its own from the uploads'. The worker takes what was posted here first.

Endpoints

Method and path Who What
POST /videos/:owner_id/uploads signed in, may post there Begin an upload. With parent_id, a reply with a video or a GIF: owner_id is the uploader's own, no title is needed, and audience, reply rule and quoting are the thread's. The thread is asked before anything is sent, and the worker asks it again before making the reply; a thread closed meanwhile fails the upload as closed. With thread_after and after_upload, a file in a thread's note (In a thread)
POST /videos/uploads/:id/parts the uploader Addresses for some of its parts
POST /videos/uploads/:id/complete the uploader All sent: hand it to the worker
GET /videos/uploads/:id the uploader How it is getting on
GET /videos/uploads signed in What they have in hand: being sent, being made, or failed in the last day
DELETE /videos/uploads/:id the uploader Give it up
GET /videos/:owner_id/ anybody A profile's videos; with ?type=audio, its audio posts
GET /videos/:id whoever may see it A video post
GET /videos/:id/files/:name whoever may see it Redirect to 1080.mp4, 720.mp4, 360.mp4 or poster.jpg; an audio post's audio.m4a or cover.jpg
PATCH /videos/:id, DELETE /videos/:id whoever may edit or delete it Change its title and text; delete it and its files
PATCH /videos/:id/access, /comment-status, /reply-access, /quote-policy; PUT/DELETE /videos/:id/pin as for any post As for any post
PATCH /videos/:id/download whoever may edit it Whether it may be downloaded
GET /videos/:id/download whoever may see it, where it is allowed Redirect to the file, to be saved
POST /videos/elsewhere/:id signed in, who may see the post Have a video from another network copied here, or say it is played again: { status, reason, video }. Thirty in ten minutes
GET /videos/elsewhere/:id signed in, who may see the post How it stands: waiting, working, ready with video, failed with why, or removed

An upload belongs to whoever began it. Anybody else is told there is none.

Refusals when beginning an upload: 403 uploads_off, 413 too_large (with max_bytes), 415 not_a_video, 429 too_many; for a reply, 403 when the thread does not take the viewer's replies and 410 when what it answers was removed.

Settings

Read by video-service, video-worker and, for the first three, auth-service, which tells the web app. Set them once, where every service reads its settings: .env for docker-compose, config.env on Kubernetes.

Variable Value
VIDEO_UPLOADS on where people may post videos. Anything else, and unset, is off: no profile has the video feature (no composer, no Videos tab), and video-service refuses an upload. Videos already posted go on being shown in feeds and at their own addresses. Read by graph-grpc-service too, which is what leaves the feature off profiles
VIDEO_MAX_BYTES The largest file taken. 500 MB (524288000) unless said
VIDEO_MAX_SECONDS The longest video taken. 600, ten minutes, unless said
VIDEO_RENDITIONS The sizes made, by height. 1080,720,360 unless said; see Sizes
VIDEO_DAILY_UPLOADS How many videos one person may send in 24 hours. 20 unless said
ANIMATION_MAX_BYTES The largest GIF or animated PNG taken. 25 MB (26214400) unless said, and never more than VIDEO_MAX_BYTES
ANIMATION_MAX_SECONDS The longest one. 30 unless said, and never more than VIDEO_MAX_SECONDS
AUDIO_UPLOADS off where no sound may be posted, chosen or recorded; on unless said, where videos may be. Off, no profile has audio posts (no Audio button, no Audio tab), video-service refuses a sound (audio_off), and those posted already go on being shown. Read by graph-grpc-service, video-service and auth-service
AUDIO_RECORDING on where the web app may offer to record a sound with the microphone; off unless said, and never where AUDIO_UPLOADS is off. Recording people, and posting what one has no right to, are a site's to allow (the user, 2026-11-08): read the terms (opens in a new tab) first. A recording arrives as a file, as one chosen does, so this says what is offered, not what is taken. Read by auth-service, which says it in NodeInfo
AUDIO_MAX_BYTES The largest file taken to make an audio post. 500 MB unless said
AUDIO_MAX_SECONDS The longest audio post. 3600, an hour, unless said
REMOTE_MEDIA_MAX_BYTES The largest file from another network copied here. 100 MB unless said
REMOTE_MEDIA_MAX_SECONDS The longest. 3600, an hour, unless said
REMOTE_VIDEO_DAYS How many days a copy from another network is kept after it was last played. 7 unless said; 0 keeps them for good
VIDEO_WORK_DIR Worker only: where a video is kept while it is worked on. /work in the image. Needs room for the largest upload and everything made of it

NodeInfo's metadata has videoUploads, videoMaxBytes, videoMaxSeconds, animationMaxBytes, animationMaxSeconds, audioMaxBytes and audioMaxSeconds.

Storage

A browser sends the video to the store itself, from the web app's page, so the bucket has to allow that: a CORS rule for PUT from the web app's address. Without it every upload fails in the browser before anything is sent. On AWS S3, under the bucket's Permissions:

[
  {
    "AllowedOrigins": ["https://example.org"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["*"],
    "MaxAgeSeconds": 3000
  }
]

The origin is the address people open the web app at, exactly: scheme and host, no path. A rule naming www.example.org for an app at example.org, or the other way round, refuses every upload; list both where the app answers at both. Other stores have the same rule under their own name for it.

file-grpc-service holds each kind of large file to its place:

Where What Who writes Who reads
assets/v1/video-service/uploads/<person>/<upload>/source What was uploaded, kept as application/octet-stream whatever it is The browser, in parts The worker. Never a viewer: no address is signed for one
assets/v1/video-service/videos/<profile>/<upload>/ Each size and the poster, or an audio post's audio.m4a and cover.jpg The worker Viewers, as video/mp4, audio/mp4 or image/jpeg by its name, whatever it was stored as
assets/v1/video-service/videos/<profile>/elsewhere-<post>/720.mp4 The copy of a video from another network The worker Viewers, as above, until REMOTE_VIDEO_DAYS after it was last played

A lifecycle rule on the bucket that aborts unfinished multipart uploads after a few days is worth having: the worker aborts the ones it knows of, and the rule catches any it could not.

Running it, and not running it

make video builds and starts both containers. Set VIDEO_UPLOADS=on.

Both are optional. Without them there are no video posts, and with VIDEO_UPLOADS unset the web app offers none. With video-service running and no worker, uploads are taken and wait.

One worker makes one video at a time. Run more replicas to make more at once; each needs processor and working space of its own.

Where the code is

What Where
Beginning and finishing an upload, and how it is getting on video-service/cmd/api/handlers/video_uploads.go
Video posts: read, edit, delete, audience, replies, pin video-service/cmd/api/handlers/ (video.go, video_access.go, video_reply.go, video_pin.go)
Sending viewers to a video's files video-service/cmd/api/handlers/video_files.go
Downloading video-service/cmd/api/handlers/video_download.go, over anahita-libs/permissions/download.go (CanDownload)
The worker video-service/worker/worker.go, video-service/cmd/worker/main.go, tested in worker_test.go
What a file is, how long it runs, and the sizes made video-service/encode/encode.go (Container, ParseProbe, Plan, PlanAnimation), tested in encode_test.go and encode_ffmpeg_test.go
The uploads video-service/data/repositories/uploads.go, table video_uploads, tested in uploads_integration_test.go
Where large files may be written and read file-grpc-service/data/services/uploads.go (UploadsPrefix, WorkerPrefix)
Audio posts video-service/encode/audio.go (tested in audio_test.go), video-service/worker/worker.go (makeAudio), anahita-libs/videos/audio.go; the kind of upload in video_uploads.kind
Videos from other networks video-service/cmd/api/handlers/elsewhere.go, video-service/worker/elsewhere.go (tested in elsewhere_test.go), video-service/data/repositories/elsewhere.go, table media_elsewhere; what a post says of one, anahita-libs/videos/elsewhere.go; kept when a post arrives by atproto-service/cmd/api/handlers/elsewhere.go and activitypub-service/cmd/api/handlers/inbox.go
Settings video-service/config/config.go, anahita-libs/videos/settings.go
The two images dockerfiles/video-service.dockerfile, dockerfiles/video-worker.dockerfile

What is not built

  1. Telling the uploader, by a notification, that a video is ready or has failed. The composer asks.
  2. Changing size while playing (HLS), captions, and a choice of poster.
  3. Sound from other networks played here: phase 3 of Audio and video from everywhere (opens in a new tab); a sound from Mastodon leads to its page until then.
  4. Animated WebP, until ffmpeg reads one; and keeping what is see-through in a GIF (WebM with transparency, or keeping the picture as it was).

From anahitasocial/anahita-services, 2026-11-09.

Written by Claude, reviewed by Rastin Mehr · About this