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
- Upload an original video directly to object storage, or paste an authorised YouTube URL.
- Render validates the request, creates persistent metadata, and signs a job for the external worker. It never downloads the full source video.
- 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.
- Candidate moments are segmented and scored.
- The selected saved template is rendered into every clip.
- A shuffled nasheed is physically mixed into every final MP4.
- FFmpeg verifies video, audio, resolution, captions, template and music.
- Strong clips can be approved and scheduled automatically.
- 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
- Run System check.
- Upload at least one nasheed in Music. Two or more are better for rotation.
- Open Templates, choose a built-in preset or duplicate one and customise it.
- Set clip count/duration and automation thresholds.
- Submit one short authorised lecture.
- Review the generated thumbnails, caption timing, crop and music level.
- 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.
