DeenClipped

AI video clipper that turns long videos and Islamic lectures into review-ready short-form clips. Live at deenclipped.online.

Paste a YouTube link or upload an MP4, mark the minutes worth clipping, and get back vertical clips with burned-in captions — each one waiting in a review queue for a person to approve or reject before anything publishes.

What it does

• Clips on meaning, not on a timer. The selected stretch is transcribed with word-level timings, then a self-hosted model scores the moments inside it and says why: complete ending, question hook, stands alone.
• Captions in the language actually spoken. English, Arabic or Urdu, or auto-detect that switches per segment — so an English lecture containing recitation is handled as both rather than mangled into one.
• Quran-aware. Recited scripture is matched against all 6,236 ayat and rendered as the verse with its translation in Amiri, not as a phonetic guess. Any clip carrying scripture is forced through human review, and that gate cannot be switched off.
• Vertical and framed. Face detection crops 16:9 to 9:16 and keeps the speaker in frame. A nasheed is mixed under the speech and ducked beneath it.
• You approve, then it publishes. Approved clips fill posting windows and go to your own connected YouTube, TikTok, Instagram and Facebook accounts. Each destination reports its own state, so one platform refusing does not mark the whole clip failed.

How this repository relates to production

Two halves, deployed separately:

Part	What it is	Deploy
src/	The web app — accounts, billing, review queue, scheduling, publishing, the public site	Pushing deenclipped-v2-2 deploys it to Render automatically
worker/	Video import, Whisper, scoring, FFmpeg/libass rendering, object storage	Manual. A push does not deploy it; see .claude/skills/deploy-worker

No npm dependencies, and the Python tests use only the standard library — a clean checkout runs the whole suite (npm run check && npm test) anywhere.

Working conventions, invariants and the reasoning behind them live in CLAUDE.md; it is the handover between sessions and the most useful file here for understanding why the code looks the way it does.

Automated workflow

1. Upload an original video directly to object storage, or paste an authorised YouTube URL.
2. Render validates the request, creates persistent metadata, and signs a job for the external worker. It never downloads the full source video.
3. The worker downloads only the selected stretch with its own yt-dlp, behind a rotating pool of static residential proxies, then runs Faster-Whisper in CPU INT8 mode.
4. Candidate moments are segmented and scored.
5. The selected saved template is rendered into every clip.
6. A shuffled nasheed is physically mixed into every final MP4.
7. FFmpeg verifies video, audio, resolution, captions, template and music.
8. Strong clips can be approved and scheduled automatically.
9. Enabled destinations publish at the selected time and store real platform post IDs.

No Opus processing credits are used.

Mandatory safeguards

The backend blocks submission or posting when any required part is missing:

• no valid template,
• no uploaded nasheed,
• failed caption/template render,
• missing audio or video stream,
• wrong output resolution,
• unverified final MP4.

Possible Quran or hadith quotations are held for review by default.

Production deployment

Use the root render.yaml for the lightweight Node web/API service and worker/docker-compose.yml for the CPU worker on an Ubuntu VPS. Render retains a small metadata disk; source videos, clips, thumbnails, and transcripts live in S3-compatible object storage. Full setup, firewall, update, and log commands are in docs/EXTERNAL_WORKER.md.

First app setup

1. Run System check.
2. Upload at least one nasheed in Music. Two or more are better for rotation.
3. Open Templates, choose a built-in preset or duplicate one and customise it.
4. Set clip count/duration and automation thresholds.
5. Submit one short authorised lecture.
6. Review the generated thumbnails, caption timing, crop and music level.
7. Test a private YouTube upload before enabling public or multi-platform publishing.

Publishing credentials

Register these exact callbacks using your deployed hostname:

https://YOUR-APP.onrender.com/auth/youtube/callback
https://YOUR-APP.onrender.com/auth/meta/callback
https://YOUR-APP.onrender.com/auth/tiktok/callback

Render environment variables:

APP_PASSWORD=choose-a-strong-password
SOCIAL_PUBLISH_ENABLED=true
SOCIAL_TOKEN_KEY=stable-random-secret-at-least-32-characters

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

META_APP_ID=
META_APP_SECRET=

TIKTOK_CLIENT_KEY=
TIKTOK_CLIENT_SECRET=

Never change SOCIAL_TOKEN_KEY after connecting accounts, or stored tokens will become unreadable. See AUTOMATIC-PUBLISHING-SETUP.md for provider steps.

Public Google sign-in

Create a Google OAuth 2.0 Web application client and register this exact authorised redirect URI:

https://deenclipped.online/auth/google/callback

Set the OAuth app audience to External, publish it to In production, and configure these Render variables:

AUTH_REQUIRED=true
PUBLIC_BASE_URL=https://deenclipped.online
GOOGLE_SIGNIN_CLIENT_ID=
GOOGLE_SIGNIN_CLIENT_SECRET=
GOOGLE_SIGNIN_REDIRECT_URI=https://deenclipped.online/auth/google/callback

Google compares redirect URIs exactly, including scheme, hostname, path and trailing slash. Account sign-in credentials are intentionally separate from the YouTube publishing credentials.

The production YouTube publishing OAuth client must also register this exact redirect URI:

https://deenclipped.online/auth/youtube/callback

The complete Google OAuth and YouTube approval checklist, scope justifications, reviewer demo script and copy-ready audit answers are in docs/YOUTUBE_VERIFICATION.md.

YouTube source imports

Do not request or store customer browser cookies. YouTube URLs are validated on Render and sent as metadata to the worker. The worker calls the configurable managed provider; the default FFMPEGAPI adapter follows its documented youtube_to_mp4 response. Playlists, unsupported URLs, provider failures, and oversized videos direct the user to Upload MP4. MP4, MOV, M4V, WebM and MKV uploads go directly from the browser to object storage.

Local installation

Requirements: Node.js 22+, Python 3.11+, FFmpeg and FFprobe.

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r worker/requirements.txt
npm install
cp .env.example .env
npm start

Validation:

npm run check
npm test
./scripts/smoke-test.sh

Rights and religious accuracy

Only process content and nasheeds you own or are authorised to reuse. AI transcripts are not authoritative Quran or hadith text. Review quotations and references before public posting.