autoclip - Moses Yebei

The Problem

Content creators often spend hours manually sifting through long videos to find highlights. The process requires downloading, transcribing, analyzing, and cutting video segments—tasks that are repetitive and error‑prone. A unified system that automates download, AI‑based highlight detection, and clip generation would save time and reduce manual effort.

What This Does

AutoClip automates the entire highlight‑generation workflow.

The FastAPI backend (backend/main.py) exposes REST endpoints (see backend/api/v1/*.py) for downloading videos from YouTube and B站, triggering AI analysis, and retrieving processed clips.
The processing pipeline is split into five stages (backend/pipeline/step1_outline.py → step5_clustering.py), each wrapped by backend/services/processing_service.py and orchestrated by backend/services/processing_orchestrator.py.
Asynchronous jobs are dispatched through Celery (backend/cli.py, backend/desktop_main.py), with progress pushed via WebSocket (backend/api/v1/websocket.py).
The React frontend (frontend/src/App.tsx) consumes these APIs, shows real‑time progress, and lets users arrange or edit generated clips.

How It Is Wired

Responsibility	File	Key Functions	External Interaction
Application bootstrap	`backend/main.py`	`create_app()`	Instantiates FastAPI, calls `app_factory`.
Router registration	`backend/app_factory.py`	`register_routes()`	Imports `backend/api/v1/*.py` and mounts them.
API endpoints	`backend/api/v1/processing.py`	`process_video()`	Calls `backend/services/processing_service.process()`.
Task orchestration	`backend/services/processing_orchestrator.py`	`run_pipeline()`	Invokes `step1_outline` → `step5_clustering`.
Database access	`backend/repositories/*.py`	`Repository.get_by_id()`	Uses `backend/core/database.py` (SQLite by default).
Celery worker	`backend/cli.py`	`start_celery()`	Spins up worker, listens to Redis.
WebSocket	`backend/api/v1/websocket.py`	`connect()`	Streams progress events to clients.
Frontend	`frontend/src/App.tsx`	`useEffect` hooks	Calls `/api/v1/processing/`, subscribes to `/ws`.

Execution starts at backend/main.py. A GET to /api/v1/processing/ triggers process_video(), which hands the job to Celery. The worker calls processing_service.process(), which delegates to processing_orchestrator.run_pipeline(). Each step writes temporary files to backend/core/unified_storage.py, updates the SQLite database via the repositories, and emits progress through the WebSocket. The React app displays progress, then lists the generated clips for user interaction.

The module graph has a single hub in backend/app_factory.py; changing any router requires updating this file. No circular imports exist, but the orchestrator’s tight coupling to the step modules means altering a step requires updating the orchestrator.

How To Use It

# 1. Clone
git clone https://github.com/moses-y/autoclip
cd autoclip

# 2. Build Docker images (recommended)
docker build -t autoclip:latest -f Dockerfile .

# 3. Start services
docker-compose up -d  # spins up FastAPI, Redis, Celery

# 4. Verify backend
curl http://localhost:8000/docs  # OpenAPI UI

# 5. Run frontend
cd frontend && npm ci && npm run dev

Configuration

Environment variables are read from backend/.env (see backend/core/config.py).
Redis URL, database path, and AI provider keys must be set.
The default AI provider is 通义千问; swap to another by editing backend/core/llm_manager.py.

Running the CLI

# Trigger a manual pipeline via CLI
python backend/cli.py process https://www.youtube.com/watch?v=XXXX

Real-World Use

A marketing team uploads a 2‑hour interview. They hit “Generate Highlights” on the web UI. The backend downloads the video, runs the AI pipeline (outline → timeline → scoring → title → clustering → video), and streams progress to the client. Once done, the UI presents a drag‑and‑drop list of 8‑second clips for quick social‑media publishing.

Code Health & Issues

Tests: 16 test files under backend/tests/ and frontend/tests/.
CI: /.github/workflows/ci.yml runs linting, unit tests, and builds Docker images.
License: MIT (LICENSE).
Documentation: 53 markdown files, including README.md and STARTUP_GUIDE.md.
Observations
Low: No missing __init__ files.
Low: All database accesses go through repository classes.
Medium: The orchestrator tightly couples to step modules; refactoring steps requires touching processing_orchestrator.py.
Low: No obvious secrets committed.

The Bottom Line

AutoClip delivers a complete, Docker‑ready pipeline for AI‑driven video highlight extraction. Its modular design—FastAPI + Celery + React—makes it easy to extend or replace individual components. The tight coupling in the orchestrator is the main architectural cost but does not impede day‑to‑day usage. The project is suitable for teams that need rapid video content creation without building the infrastructure from scratch.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

546 files

Python185
TSX64
Markdown61
TypeScript24
JSON18
Shell14

ReactDjangoFlaskTailwindDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["backend<br/>180 modules"] g1["frontend<br/>90 modules"] g2["(root)<br/>3 modules"] g3["scripts<br/>2 modules"] g2 -->|7| g0

Module dependencies

The 10 most depended-upon modules of 275, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_backend_core_database["database"] n1_backend_models_project["project"] n2_backend_models_task["task"] n3_frontend_src_services_api["api"] n4_backend_core_path_utils["path_utils"] n5_backend_core_config["config"] n6_backend_models_clip["clip"] n7_nd_src_store_useProjectStore["useProjectStore"] n8_backend_core_shared_config["shared_config"] n9_backend_models_collection["collection"] n5_backend_core_config --> n4_backend_core_path_utils n0_backend_core_database --> n5_backend_core_config n3_frontend_src_services_api --> n7_nd_src_store_useProjectStore n7_nd_src_store_useProjectStore --> n3_frontend_src_services_api classDef cyc stroke:#ef4444,stroke-width:2px; class n3_frontend_src_services_api,n7_nd_src_store_useProjectStore cyc;

Dependencies

18 of 40 declared dependencies are a major version behind. Resolved 40 of 40 against the registry.

Package	Declared	Latest	Behind
`react-dropzone`	^14.2.3	20.1.0	6 major
`eslint-plugin-react-hooks`	^4.6.0	7.1.1	3 major
`vite`	^5.0.8	8.2.1	3 major
`@typescript-eslint/eslint-plugin`	^6.14.0	8.67.0	2 major
`@typescript-eslint/parser`	^6.14.0	8.67.0	2 major
`@vitejs/plugin-react`	^4.2.1	6.0.5	2 major
`eslint`	^8.55.0	10.8.1	2 major
`typescript`	^5.2.2	7.0.2	2 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh3 occurrences

.github/workflows

dtolnay/rust-toolchain@stable, Swatinem/rust-cache@v2, softprops/action-gh-release@v2

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/ci.yml

line 31 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/ci.yml

3 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

6 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium3 occurrences

Dockerfile

node:18-slim, python:3.11-slim, python:3.11-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/desktop-build.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.