Looped

Posted on May 24

I Built Cuekiyo: a Local-First Anime OP/ED Video Pipeline with React, FastAPI, yt-dlp and FFmpeg

#opensource #react #fastapi #ffmpeg

I just released Cuekiyo v1.0.0, an open-source local web app for building anime opening and ending compilation videos.

The idea is simple:

Pick anime titles → approve OP/ED songs → review YouTube clip candidates → export a finished MP4.

No cloud editor. No upload step. No paid API dependency. The whole thing runs on your machine.

GitHub: https://github.com/unloopedmido/cuekiyo

I built this because the manual workflow for making anime opening/ending compilations is honestly painful. You end up with a bunch of browser tabs, copied timestamps, separate download commands, trimming tools, naming chaos, random folders, and repeated re-renders whenever one clip changes.

Cuekiyo turns that into a guided local pipeline. It automates the boring parts, but still pauses at the moments where a human should make the decision.

The problem

Making a compilation video sounds simple until you actually try to do it cleanly.

A typical manual workflow looks something like this:

Pick the anime you want to include.
Find the opening and ending theme names.
Search YouTube for each song.
Check which uploads are usable.
Copy links or timestamps somewhere.
Download the source videos.
Trim each clip.
Normalize or at least avoid wildly inconsistent audio.
Add title overlays/lower-thirds.
Stitch everything together.
Re-render when something is wrong.

That is not hard once. The problem is repetition.

If you are making one clip, a normal video editor is enough. If you are making a structured compilation with many anime titles, many theme songs, multiple sources, consistent overlays, and predictable output folders, the workflow becomes more like a small media pipeline than a one-off edit.

That was the actual problem I wanted to solve.

Not “replace video editors.”

More like:

Give me a local studio that handles the repetitive pipeline work, while still letting me control the creative choices.

What Cuekiyo does

Cuekiyo is built around a guided project flow.

You create a project, choose anime titles, select whether you want openings, endings, or both, then move through a set of approval steps.

The core flow is:

Create a project
Name it, choose anime titles, pick the song types, and configure overlay/render defaults.
Select songs
Cuekiyo loads theme data and lets you approve which OP/ED tracks should be included.
Review clip candidates
The app sources YouTube candidates, but you still choose what actually gets used. You can also paste your own link when automation gets it wrong.
Trim and process clips
Cuekiyo downloads, probes, normalizes, cuts, and overlays clips locally.
Confirm render order
You choose the final order before rendering.
Export MP4
The final compilation is written to your local project folder.

The important design rule was this:

Automation should handle labor, not taste.

That is why Cuekiyo pauses at user gates. Choosing the right song, source clip, trim point, and final order is subjective. A pipeline can help, but it should not pretend to know your taste better than you do.

Why local-first?

I wanted Cuekiyo to feel like a desktop creative tool, but with the development speed and UI flexibility of a web app.

So instead of building a hosted SaaS product, Cuekiyo runs locally:

The backend runs on your machine.
The frontend runs in your browser.
Project state lives in SQLite.
Media files live under data/projects/{id}/.
Rendering happens through local FFmpeg.
Nothing needs to be uploaded to a random cloud service.

That matters for this kind of app because video files are large, copyrighted media has legal/terms-of-service complexity, and creators often want direct control over their own files.

Local-first also keeps the project simpler operationally. There is no user account system, no storage billing, no hosted render queue, no cloud worker fleet, and no database server to maintain.

The trade-off is that users need local dependencies installed: Python, Node.js, FFmpeg, FFprobe, and yt-dlp. For v1, I accepted that trade-off because I wanted to ship the core product first.

Long term, I want the install experience to become much closer to “download, open, create.”

The stack

Cuekiyo is split into a FastAPI backend and a React frontend.

The main stack is:

Backend: FastAPI, SQLAlchemy, SQLite
Frontend: React 19, Vite, Tailwind CSS, shadcn/ui, React Router
Media: FFmpeg, FFprobe, yt-dlp
Overlay rendering: Satori-based HTML-to-PNG overlays
Metadata: Jikan and AniList
Progress updates: WebSockets
Project storage: local SQLite database + local filesystem

The frontend handles the guided workflow and review screens. The backend owns the pipeline, state transitions, media processing, and filesystem safety.

The architecture

At a high level, Cuekiyo is a state machine wrapped around a media pipeline.

The pipeline goes through stages like:

DRAFT
→ LOAD_THEMES
→ SONG_SELECTION
→ SOURCING
→ AWAITING_CANDIDATES
→ DOWNLOADING
→ PROBING_NORMALIZING
→ CUTTING
→ OVERLAYING
→ AWAITING_RENDER_ORDER
→ RENDERING
→ COMPLETED

Some stages run automatically. Others are user gates.

The user gates are the important part:

Song selection
Candidate review
Optional trim/review decisions
Final render order

Everything else can be automated.

A single FastAPI process owns the pipeline. Jobs run in background threads, and progress is pushed to the frontend over WebSockets. SQLite stores the project state, job state, and a heartbeat for the active pipeline lock.

For v1, Cuekiyo uses one global pipeline lock. That means one project renders/processes at a time. This is intentionally simple. It avoids a lot of messy cross-project concurrency bugs while keeping crash recovery understandable.

Is it the final architecture forever? No.

But for a v1 local app, it is honest and maintainable.

The media pipeline

The hardest part of Cuekiyo was not making a nice UI.

The hardest part was making a media pipeline that does not immediately collapse under real-world weirdness.

External media tools are powerful, but they fail in many ways:

A source video disappears.
yt-dlp returns unexpected metadata.
FFmpeg fails because of an encoder issue.
A clip has weird duration or stream data.
A path contains characters you forgot to handle.
GPU encoding works on your machine but not someone else’s.
A downloaded file exists, but a later processing artifact does not.

Cuekiyo tries to make those problems manageable by treating each stage as a separate pipeline step.

Downloads, probing, normalization, cutting, overlaying, and rendering are distinct operations. That makes the flow easier to inspect, easier to retry, and easier to explain in the UI.

I also made a point of passing subprocess arguments as argument arrays instead of shell strings. For a local media tool that touches user-provided links and filesystem paths, that is not optional polish. It is baseline safety.

GPU encoding and fallback

One feature I wanted early was NVIDIA NVENC support.

A lot of people doing local video work have NVIDIA GPUs, and hardware encoding can make rendering much faster. But hard-requiring NVENC would be a bad idea because not every machine supports it, and FFmpeg builds vary.

So Cuekiyo probes for NVENC support and falls back to CPU encoding with libx264 when needed.

That kind of fallback matters because local-first software has to handle different user machines gracefully. You cannot assume the environment is exactly like yours.

The frontend

The frontend is built with React 19, Vite, Tailwind CSS, shadcn/ui, and React Router.

The UI goal was not to look like a raw admin dashboard. I wanted it to feel more like a creative tool:

project cards
guided steps
clear status states
clip candidate review
visible progress
settings that affect the pipeline without feeling scary

The frontend talks to the backend through API routes and WebSocket progress events. That live progress feedback is important because media work can take time. If the UI just sits there silently while FFmpeg runs, users assume something broke.

Even when the backend is doing heavy work, the frontend should make the pipeline feel understandable.

The biggest design decision: pause only when the user needs to choose

A lot of automation tools make one of two mistakes:

They automate too little, so the user still does all the boring work.
They automate too much, so the user has to clean up wrong decisions afterward.

Cuekiyo’s middle ground is the user gate model.

The app should not ask for confirmation after every tiny technical step. That would be annoying.

But it also should not silently pick every YouTube source and every final order without review. That would be risky.

So the pipeline auto-advances through mechanical stages and pauses at taste-based decisions.

That model ended up making the product feel much better. It also made the backend easier to reason about because gated states became explicit parts of the state machine instead of random UI conditions.

Known v1 trade-offs

Cuekiyo v1.0.0 is not perfect, and I do not want to pretend it is.

The biggest v1 trade-offs are:

One pipeline job at a time

The global lock keeps the job runner simple and prevents multiple projects from fighting over local resources. The downside is that cross-project parallelism is not supported yet.

For a local v1 release, I think this is acceptable. Parallel jobs are on the roadmap.

Simplified concat/crossfade graph

The current rendering path supports the compilation flow, but the FFmpeg filter graph can become more sophisticated. A richer render graph would make future transitions and multi-clip layouts easier.

Retry can be smarter

The current retry flow is good enough for the v1 model, but a more durable per-stage cursor would be better. That would let the app resume from the exact failed boundary instead of inferring it.

These are not hidden issues. They are documented because I would rather be honest about the architecture than pretend every v1 decision is final.

What I learned

Building Cuekiyo taught me a few things.

1. Local-first apps still need product thinking

It is easy to think “local tool” means “developer utility.” But Cuekiyo is not just a script with a UI. It needs onboarding, clear states, useful errors, and a workflow that makes sense to a non-author.

The fact that it runs locally does not remove the need for product design.

2. State machines are worth it for workflow-heavy apps

Once an app has long-running jobs, user gates, retries, failures, cancellations, and progress events, implicit state becomes painful fast.

Making the pipeline states explicit helped a lot.

3. FFmpeg is powerful, but the wrapper code matters

FFmpeg can do almost anything, but users should not have to care about the command graph. The real work is building a safe, inspectable layer around it.

4. “Automate everything” is not always the right product

The best version of Cuekiyo is not a bot that blindly creates videos. It is a studio that removes repetitive labor while keeping human choice in the loop.

That distinction changed how I designed the whole app.

What is next

Now that v1.0.0 is public, the next focus is making Cuekiyo easier to try.

The biggest priorities are:

A better first-run experience
A portable desktop-style release
Better install/dependency checks
Smarter retry behavior
Parallel project jobs
Richer render/crossfade options
More creator-focused docs and demos

The core pipeline works, but discoverability and install friction matter a lot for open-source projects. If someone is interested, they should be able to understand and try the project quickly.

Final thoughts

Cuekiyo started as a niche idea, but it became one of the most complete projects I have built so far.

It combines full-stack app development, local-first architecture, media processing, background jobs, WebSocket progress, UI/UX design, and release engineering into one project.

That is exactly the kind of project I wanted in my portfolio: not just a demo, but an actual tool with product decisions, trade-offs, and a real workflow.

If you are interested in local-first tools, media automation, React/FastAPI apps, or just weirdly specific open-source software, feel free to check it out.