Build Log: End-to-End Text Overlay Workflow for Video Processing

Today I completed the core text overlay workflow across the frontend, backend, and worker pipeline. The main goal was to make text overlays behave like a real production feature instead of a partial UI action. That meant saving overlays, enqueueing processing jobs, running worker execution, tracking status, and making sure users can download the final processed file when rendering is complete.

What changed

The biggest update was implementing the full text overlay processing lifecycle from the UI down to the background worker.

A user can now create overlays for a video, save them through the API, enqueue a rendering job, and return to the videos page while processing continues in the background. Once the job is finished, the videos listing reflects that state and download actions point to the processed overlay output instead of the original file.

I also finalized one important behavior change in overlay saving. Instead of merging new overlays with existing ones, each save call now replaces the stored overlays for that video. This prevents stale overlay entries from lingering and causing recurring overlap conflicts.

Backend work completed

On the backend, I added the API and queue flow required to support the feature end to end.

The following routes are now in place:

• POST /videos/{video_id}/text-overlays
• POST /enqueue/text-overlay
• GET /text-overlay-jobs
• GET /videos/{video_id}/text-overlays/download

The save endpoint now stores the submitted overlays for a given video. The enqueue endpoint pushes a text overlay processing job into the queue and returns quickly, so the frontend does not need to wait on worker readiness before moving forward.

To support job visibility, I introduced a text_overlay_jobs collection for tracking processing records. This collection is now used for queued, pending, finished, and failure state tracking. I also added the required database initialization and an index on text_overlay_jobs.video_id so lookup remains efficient.

On the worker side, I added process_text_overlay_job and wired a dedicated text_overlay_worker into the queue system using TEXT_OVERLAY_QUEUE_NAME. That worker is also registered in the control panel worker setup so it is managed consistently with the rest of the background processing stack.

Another important backend fix was changing overlay persistence behavior from merge to replace. Earlier behavior allowed stale overlays to remain in the record, which could trigger overlap validation conflicts even after the user thought they had corrected the layout. Replacing overlays on save solved that problem cleanly.

Frontend updates

On the frontend, the CreateTextOverlayPage is now connected to the real processing flow.

The Done / Process Video action now performs the expected sequence:

1. Save overlays
2. Enqueue the text overlay job
3. Redirect the user back to /videos

I also added a loading and disabled state to prevent duplicate submissions while the request is in progress. This gives the action more predictable UX and reduces accidental repeat clicks.

Error handling was improved as well. Instead of showing vague failures, the frontend now parses backend validation messages more clearly, including field paths where possible. That makes it much easier to debug malformed overlay payloads during testing.

Because some UI controls are still not finalized, I added temporary default values for fields that are not yet exposed in the interface. Current defaults are:

• position: top/center
• style: font size 16, weight normal

These defaults let the feature move forward without blocking on the final design of overlay controls.

Videos page behavior

I also updated the /videos listing page so the new workflow feels integrated instead of isolated.

The Video ID column was removed to simplify the table and give more room to user-facing actions.

The Text Overlay column now reflects job state more meaningfully. If the overlay job for a video is finished, the action shows Done. Otherwise, it shows Create.

Download behavior was also updated. When an overlay job is finished successfully, the output and error download actions now point to the processed overlay video instead of the original file. If overlay processing has not completed, downloads continue to use the regular video file.

That small change is important because it makes the final output feel connected to the workflow the user just triggered.

Why the replace-on-save decision mattered

One of the more important logic decisions today was changing overlay saving from merge semantics to replace semantics.

Merging sounds convenient at first, but in practice it created stale state problems. Old overlays could remain attached to the video even after the user thought they were working from a clean set. That caused overlap validation issues to reappear and made the experience feel inconsistent.

Replacing overlays on each save call makes the system much more predictable. The saved overlays now reflect exactly what the user submitted in the latest request, which is the safer behavior for this kind of editor flow.

Current workflow

At this point, the text overlay feature supports the following flow:

• User opens the text overlay page for a video
• User adds or edits overlays
• Frontend saves the overlays
• Frontend enqueues a processing job
• Worker renders the text overlay output in the background
• Job status is tracked in text_overlay_jobs
• Videos page reflects completion state
• Download action serves the overlay-rendered file when available

That means the feature is now functional across storage, processing, status tracking, and output retrieval.

What is still temporary

A few parts are still intentionally temporary or transitional.

The overlay editor is still using fallback defaults for position and style where dedicated UI controls have not been built yet. The current implementation is enough to keep the workflow functional, but the page still needs the final interactive form controls for layout and style management.

The videos page is also currently showing a simplified status signal. This works for now, but it could later become more expressive with states like queued, processing, failed, and finished.

Final result

This was a solid progress day because the feature moved from partial UI scaffolding into a real end-to-end system. The frontend now triggers meaningful backend work, the worker actually processes jobs, job state is persisted, and the final output can be downloaded through the app.

Most importantly, the workflow now behaves in a predictable way. Saving overlays replaces prior state, queueing does not block on hard worker health checks, and completed processing is reflected directly in the videos list.

The next step is to improve the overlay editor UI itself, but the underlying pipeline is now in place.