Nov 18, 202610 min read

Video Transcoding Backend: Uploads, Job Queue and Renditions on Your Own Cloud

Design a video pipeline that takes direct uploads to a private bucket, queues one transcode per video, writes an MP4 rendition ladder with ffmpeg to a CDN-backed bucket and survives duplicate deliveries, then implement it in Go.

Illustration for Video Transcoding Backend: Uploads, Job Queue and Renditions on Your Own Cloud

A video product for courses, user clips or marketing needs one backend job: accept a large upload without routing it through the API, turn it into playable renditions, and serve them from a CDN. The hard parts start with an upload that may never finish, and continue with a queue that delivers twice and an encode that takes minutes.

This guide designs that pipeline from direct upload to a ready video, starting with the state machine and data model. It then covers managed transcoders on AWS and GCP and builds the ffmpeg version in Go with Encore, in your own cloud account.

The Transcoding Backend at a Glance

JobPatternHand-built on AWSWith Encore in your AWS or GCP account
UploadSigned PUT URL to a private bucketS3 presigned URLSignedUploadURL on a private bucket
ConfirmClient calls the API, which checks the object existsAPI on Lambda or ECSAPI endpoint with Exists
QueueOne message per video, at-least-onceSQS with a DLQTopic and subscription with a retry policy
Encodeffmpeg per rendition heightECS task or MediaConvert jobSubscription handler running ffmpeg
ServePublic renditions behind a CDNS3 with CloudFrontPublic bucket, CDN provisioned
StateStatus column with conditional transitionsRDSPostgres database with migrations

The Video State Machine

Each video moves through five states, and every transition is a conditional UPDATE so a retry or a double click cannot skip a step:

  • uploading: the row exists and the client has a signed URL, but the file may not be there yet.
  • queued: the API saw the object in the bucket and published one transcode message.
  • transcoding: a worker claimed the video. A retried message may claim it again, which is safe since outputs are overwritten by key.
  • ready: every rendition is uploaded and recorded.
  • failed: retries ran out, and the message is in the dead-letter queue for inspection.

Videos that stay in uploading for a day are abandoned uploads, and a cleanup job can delete the rows and any partial objects.

A Data Model That Enforces the Rules

The CHECK constraint keeps the status to known values, source_key is unique so two videos cannot share an upload, and the rendition primary key makes the write idempotent:

CREATE TABLE videos ( id BIGSERIAL PRIMARY KEY, owner_id TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'uploading' CHECK (status IN ('uploading', 'queued', 'transcoding', 'ready', 'failed')), source_key TEXT NOT NULL UNIQUE, attempts INT NOT NULL DEFAULT 0, last_error TEXT, created_at TIMESTAMPTZ NOT NULL DEFAULT now() ); CREATE TABLE renditions ( video_id BIGINT NOT NULL REFERENCES videos(id), height INT NOT NULL, object_key TEXT NOT NULL, bytes BIGINT NOT NULL, PRIMARY KEY (video_id, height) );

Upload Directly, Not Through the API

Proxying a 2 GB file through an API server ties up a connection for minutes and runs into request body limits. A signed upload URL lets the client send the file straight to the bucket, with the URL expiring after 15 minutes. The API only creates the row and signs the URL, and the client calls back when the upload finishes.

How Do You Build It by Hand on AWS?

On AWS the pieces are an S3 bucket for uploads with a CORS rule for PUT, presigned URLs from the SDK, an SQS queue with a dead-letter queue, a worker on ECS Fargate with ffmpeg in its image, a second bucket for renditions behind CloudFront with origin access control, RDS for the status table, and IAM roles for the API and the worker. For long files or HLS output, the worker submits an AWS Elemental MediaConvert job instead and listens for its completion event. On GCP the managed option is the Transcoder API. The S3 presigned URLs guide and the CloudFront Terraform guide cover two of those pieces.

How Do You Build It with Encore?

Encore

Encore is a backend framework with built-in infrastructure for Go and TypeScript. The database, both buckets, the topic and the subscription are declared in the service code, and deploying to your AWS or GCP account provisions RDS or Cloud SQL, S3 or GCS with a CDN for the public bucket, and SNS with SQS or Pub/Sub. Encore provisions an IAM role for the service.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

Uploads and the Transcode Queue

The API creates the row, signs the upload URL and, once the client reports the upload done, checks the object and queues exactly one transcode:

package videos import ( "context" "fmt" "time" "encore.dev/beta/auth" "encore.dev/beta/errs" "encore.dev/pubsub" "encore.dev/storage/objects" "encore.dev/storage/sqldb" ) var db = sqldb.NewDatabase("videos", sqldb.DatabaseConfig{Migrations: "./migrations"}) // Private bucket for original uploads. var uploads = objects.NewBucket("uploads", objects.BucketConfig{}) // Public bucket for renditions, served through a CDN. var renditions = objects.NewBucket("renditions", objects.BucketConfig{Public: true}) type TranscodeRequested struct { VideoID int64 } var transcodeRequests = pubsub.NewTopic[*TranscodeRequested]("transcode-requested", pubsub.TopicConfig{ DeliveryGuarantee: pubsub.AtLeastOnce, }) type CreateResponse struct { VideoID int64 `json:"video_id"` UploadURL string `json:"upload_url"` } // Create registers a video and returns a signed URL the client uploads to directly. // //encore:api auth method=POST path=/videos func Create(ctx context.Context) (*CreateResponse, error) { owner, _ := auth.UserID() key := fmt.Sprintf("%s/%d.mp4", owner, time.Now().UnixNano()) var id int64 err := db.QueryRow(ctx, `INSERT INTO videos (owner_id, source_key) VALUES ($1, $2) RETURNING id`, string(owner), key).Scan(&id) if err != nil { return nil, err } u, err := uploads.SignedUploadURL(ctx, key, objects.WithTTL(15*time.Minute)) if err != nil { return nil, err } return &CreateResponse{VideoID: id, UploadURL: u.URL}, nil } // Uploaded queues the transcode once the client has finished the upload. // The conditional UPDATE makes repeated calls harmless. // //encore:api auth method=POST path=/videos/:id/uploaded func Uploaded(ctx context.Context, id int64) error { owner, _ := auth.UserID() var key string if err := db.QueryRow(ctx, `SELECT source_key FROM videos WHERE id = $1 AND owner_id = $2`, id, string(owner)).Scan(&key); err != nil { return &errs.Error{Code: errs.NotFound, Message: "unknown video"} } ok, err := uploads.Exists(ctx, key) if err != nil { return err } if !ok { return &errs.Error{Code: errs.FailedPrecondition, Message: "upload not found"} } res, err := db.Exec(ctx, `UPDATE videos SET status = 'queued' WHERE id = $1 AND status = 'uploading'`, id) if err != nil { return err } if res.RowsAffected() == 0 { return nil } _, err = transcodeRequests.Publish(ctx, &TranscodeRequested{VideoID: id}) return err } type Rendition struct { Height int `json:"height"` URL string `json:"url"` } type Video struct { Status string `json:"status"` Renditions []Rendition `json:"renditions"` } // Get returns the status and the CDN URLs of finished renditions. // //encore:api auth method=GET path=/videos/:id func Get(ctx context.Context, id int64) (*Video, error) { owner, _ := auth.UserID() v := &Video{} if err := db.QueryRow(ctx, `SELECT status FROM videos WHERE id = $1 AND owner_id = $2`, id, string(owner)).Scan(&v.Status); err != nil { return nil, &errs.Error{Code: errs.NotFound, Message: "unknown video"} } rows, err := db.Query(ctx, `SELECT height, object_key FROM renditions WHERE video_id = $1 ORDER BY height DESC`, id) if err != nil { return nil, err } defer rows.Close() for rows.Next() { var r Rendition var key string if err := rows.Scan(&r.Height, &key); err != nil { return nil, err } r.URL = renditions.PublicURL(key).String() v.Renditions = append(v.Renditions, r) } return v, rows.Err() }

The Transcode Worker

The subscription claims the video, runs ffmpeg once per height and records each rendition. The ack deadline is 10 minutes, which is the most GCP Pub/Sub allows and well inside SQS's visibility limit, so this worker suits clips of a few minutes:

package videos import ( "context" "errors" "fmt" "io" "os" "os/exec" "path/filepath" "time" "encore.dev/pubsub" "encore.dev/rlog" "encore.dev/storage/sqldb" ) // Heights of the MP4 renditions to produce. var ladder = []int{1080, 720, 480} var _ = pubsub.NewSubscription(transcodeRequests, "transcode", pubsub.SubscriptionConfig[*TranscodeRequested]{ Handler: transcode, // A few minutes of video per message; longer files belong in a managed transcoder. AckDeadline: 10 * time.Minute, MaxConcurrency: 2, RetryPolicy: &pubsub.RetryPolicy{MinBackoff: 30 * time.Second, MaxRetries: 3}, }) const maxTranscodeAttempts = 4 func failOrRetry(ctx context.Context, videoID int64, cause error) error { // Record a terminal failure once retries are exhausted so clients do not see // transcoding forever after the message has gone to the dead-letter queue. if _, err := db.Exec(ctx, ` UPDATE videos SET status = 'failed', last_error = $2 WHERE id = $1 AND status = 'transcoding' AND attempts >= $3`, videoID, cause.Error(), maxTranscodeAttempts); err != nil { return err } return cause } func transcode(ctx context.Context, msg *TranscodeRequested) error { var key string err := db.QueryRow(ctx, ` UPDATE videos SET status = 'transcoding', attempts = attempts + 1 WHERE id = $1 AND status IN ('queued', 'transcoding') RETURNING source_key`, msg.VideoID).Scan(&key) if errors.Is(err, sqldb.ErrNoRows) { // Already ready or failed: a duplicate delivery, nothing to do. rlog.Info("skipping video", "video_id", msg.VideoID) return nil } else if err != nil { return err } dir, err := os.MkdirTemp("", "transcode") if err != nil { return failOrRetry(ctx, msg.VideoID, err) } defer os.RemoveAll(dir) src := filepath.Join(dir, "source") if err := download(ctx, key, src); err != nil { return failOrRetry(ctx, msg.VideoID, err) } for _, h := range ladder { out := filepath.Join(dir, fmt.Sprintf("%dp.mp4", h)) if err := encode(ctx, src, out, h); err != nil { return failOrRetry(ctx, msg.VideoID, err) } objKey := fmt.Sprintf("%d/%dp.mp4", msg.VideoID, h) size, err := upload(ctx, out, objKey) if err != nil { return failOrRetry(ctx, msg.VideoID, err) } _, err = db.Exec(ctx, ` INSERT INTO renditions (video_id, height, object_key, bytes) VALUES ($1, $2, $3, $4) ON CONFLICT (video_id, height) DO UPDATE SET bytes = EXCLUDED.bytes`, msg.VideoID, h, objKey, size) if err != nil { return failOrRetry(ctx, msg.VideoID, err) } } _, err = db.Exec(ctx, `UPDATE videos SET status = 'ready' WHERE id = $1`, msg.VideoID) if err != nil { return failOrRetry(ctx, msg.VideoID, err) } return nil } // encode scales to the target height, keeps the aspect ratio and // writes an MP4 that can start playing before it is fully downloaded. func encode(ctx context.Context, src, out string, height int) error { cmd := exec.CommandContext(ctx, "ffmpeg", "-y", "-i", src, "-vf", fmt.Sprintf("scale=-2:%d", height), "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-c:a", "aac", "-b:a", "128k", "-movflags", "+faststart", out) if b, err := cmd.CombinedOutput(); err != nil { return fmt.Errorf("ffmpeg %dp: %w: %s", height, err, b) } return nil } func download(ctx context.Context, key, path string) error { r := uploads.Download(ctx, key) defer r.Close() f, err := os.Create(path) if err != nil { return err } defer f.Close() if _, err := io.Copy(f, r); err != nil { return err } return r.Err() } func upload(ctx context.Context, path, key string) (int64, error) { f, err := os.Open(path) if err != nil { return 0, err } defer f.Close() w := renditions.Upload(ctx, key) n, err := io.Copy(w, f) if err != nil { w.Abort(err) return 0, err } return n, w.Close() }

The scale=-2:height filter keeps the aspect ratio with an even width, and +faststart moves the index to the front so playback can start before the download ends. Run against a 4-second 1920x1080 test clip with ffmpeg 7.1, the three commands produced 1920x1080, 1280x720 and 854x480 MP4 files.

Add ffmpeg to the Image

Go apps deploy on a scratch base image by default, which has no ffmpeg. The build settings in encore.app accept any publicly accessible base image. jrottenberg/ffmpeg:7.1-ubuntu2404 is a public Ubuntu 24.04 image with ffmpeg 7.1, which matches the commands above:

{ "id": "video", "build": { "docker": { "base_image": "jrottenberg/ffmpeg:7.1-ubuntu2404" } } }

The object storage, Pub/Sub and databases docs cover each primitive, and connecting your own cloud covers the AWS or GCP account. A coding agent that adds a 360p rendition or a thumbnail step edits the Go code, and the next deploy ships it with no change to queues or IAM.

Best fit: Go or TypeScript teams adding video uploads to a product who want the pipeline, buckets and CDN in their own AWS or GCP account.

Things to Decide Early

  • MP4 ladder or HLS. Progressive MP4s are simple and play everywhere. Adaptive streaming with HLS or DASH needs segmenting and a manifest, which is where MediaConvert or the Transcoder API save the most work.
  • Where long encodes run. A subscription handler fits clips that finish inside the ack deadline. Longer files belong in a managed transcoder or a batch job that reports back through the same status table.
  • Retention of originals. Keep the source file for re-encoding into new formats later, or delete it after ready to save storage, and decide before the first customer uploads.

Frequently asked questions

How do you build a video transcoding pipeline?

Clients upload the original file straight to a private bucket with a signed URL, then call the API to mark the upload done. The API moves the video to queued and publishes one message, a worker downloads the file, runs ffmpeg once per rendition height, uploads each MP4 to a public bucket behind a CDN and marks the video ready.

Should I use ffmpeg or AWS MediaConvert?

Run ffmpeg in your own workers for short clips and a simple MP4 ladder, where a 10-minute job fits inside the queue's ack deadline. Use AWS Elemental MediaConvert or the Google Cloud Transcoder API for long files, HLS or DASH packaging, DRM and captions, since they run jobs of any length and bill per output minute.

How do you stop a video from being transcoded twice?

Queues deliver at least once, so the worker claims the video with a conditional UPDATE that only matches queued or transcoding rows and skips the message when nothing matches. Renditions are keyed on video ID and height with ON CONFLICT, so a retried job overwrites its own output instead of adding rows.

How do you build a video transcoding backend with Encore?

Declare the database, the uploads and renditions buckets, the transcode topic and its subscription in Go. Deploying to your AWS or GCP account provisions Postgres, S3 or GCS buckets with a CDN for the public one, and SNS with SQS or Pub/Sub, and a custom base image adds ffmpeg to the container.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders