ctx-reels 1.0.0

package/.env.example

@@ -0,0 +1,38 @@
+# ===========================
+# CTX-Reels Configuration
+# ===========================
+
+# --- API Keys ---
+GEMINI_API_KEY=""
+ELEVENLABS_API_KEY=""
+
+# --- Voice Engine ---
+# Options: "kokoro" (free, local), "edge-tts" (free, cloud), "elevenlabs" (paid, premium)
+VOICE_ENGINE="kokoro"
+
+# Voice IDs (optional, defaults are good)
+# KOKORO_VOICE="af_heart"
+# EDGE_TTS_VOICE="en-US-ChristopherNeural"
+# ELEVENLABS_VOICE_ID="pNInz6obpgDQGcFmaJcg"
+
+# --- Paths ---
+FFMPEG_PATH="/usr/local/bin/ffmpeg"
+BG_ASSET="./templates/backgrounds/minecraft.mp4"
+# PYTHON_PATH="python3"
+
+# --- Output Directory ---
+# Default: ~/Desktop/ctx
+# CTX_OUTPUT="/path/to/custom/output"
+
+# --- Subtitle Styling (1080x1920) ---
+SUB_FONT=Impact
+SUB_SIZE=38
+SUB_COLOR=&H0000FFFF
+SUB_OUTLINE_COLOR=&H00000000
+SUB_BG_COLOR=&H80000000
+SUB_BORDER_STYLE=1
+SUB_ALIGNMENT=10
+SUB_MARGIN_V=480
+
+# --- AI Models ---
+GEMINI_MODEL=gemini-2.5-flash

package/README.md

@@ -0,0 +1,120 @@
+# 🎬 CTX-Reels
+
+**AI-powered faceless short-form video generator.** Create TikTok / Reels / Shorts from a topic in one command.
+
+```
+ctx generate -t "Cristiano Ronaldo"
+```
+
+> Script → Voice → Karaoke Subtitles → Video — all automated.
+
+---
+
+## ✨ Features
+
+- **One-command video generation** from any topic
+- **3 voice engines**: Kokoro (free, local), Edge-TTS (free, cloud), ElevenLabs (premium)
+- **Word-level karaoke subtitles** — active word highlights in white against yellow text
+- **Smart script writing** via Gemini AI with viral hooks and punchy delivery
+- **Batch generation** from a JSON file of topics
+- **Customizable** — fonts, colors, backgrounds, voices, output dir
+
+## 📦 Install
+
+```bash
+npm install -g ctx-reels
+ctx setup
+```
+
+### Prerequisites
+
+| Dependency | Required | Install |
+|---|---|---|
+| **Node.js** ≥ 18 | ✅ | [nodejs.org](https://nodejs.org) |
+| **FFmpeg** + FFprobe | ✅ | `brew install ffmpeg` / `apt install ffmpeg` |
+| **Python 3** | ✅ (for subtitles) | [python.org](https://python.org) |
+| **Gemini API Key** | ✅ (for scripts) | [aistudio.google.com](https://aistudio.google.com) |
+
+`ctx setup` will create a Python virtualenv and install `faster-whisper` automatically.
+
+## 🚀 Quick Start
+
+```bash
+# 1. Generate a full reel
+ctx generate -t "Elon Musk"
+
+# 2. Batch generate from a list
+echo '["AI Revolution", "Space Exploration", "Bitcoin"]' > topics.json
+ctx batch topics.json
+
+# 3. Run individual steps
+ctx script -t "My Topic"
+ctx voice -s output/scripts/my-topic.txt
+ctx subs -a output/audio/my-topic.mp3
+ctx render -a output/audio/my-topic.mp3 -s output/subtitles/my-topic.ass
+```
+
+## 🎤 Voice Engines
+
+| Engine | Cost | Quality | Setup |
+|---|---|---|---|
+| **Kokoro** (default) | Free | ⭐⭐⭐⭐ | Automatic (downloads 80MB model on first run) |
+| **Edge-TTS** | Free | ⭐⭐⭐ | `pip install edge-tts` |
+| **ElevenLabs** | Paid | ⭐⭐⭐⭐⭐ | API key in `.env` |
+
+```bash
+# List available voices for your engine
+ctx voices
+
+# Switch engine in .env
+VOICE_ENGINE="kokoro"    # or "edge-tts" or "elevenlabs"
+```
+
+## ⚙️ Configuration
+
+Edit `.env` (created by `ctx setup`):
+
+```env
+# API Keys
+GEMINI_API_KEY="your-key-here"
+
+# Voice
+VOICE_ENGINE="kokoro"
+KOKORO_VOICE="af_heart"
+
+# Output directory (default: ~/Desktop/ctx)
+CTX_OUTPUT="/path/to/custom/output"
+
+# Background video/image
+BG_ASSET="./templates/backgrounds/minecraft.mp4"
+```
+
+See [.env.example](.env.example) for all options.
+
+## 📁 Output Structure
+
+```
+~/Desktop/ctx/
+├── scripts/     # Generated text scripts
+├── audio/       # Generated voice audio (MP3)
+├── subtitles/   # Karaoke subtitles (ASS)
+└── reels/       # Final rendered videos (MP4)
+```
+
+## 🛠 CLI Reference
+
+| Command | Description |
+|---|---|
+| `ctx generate -t <topic>` | Full pipeline: script → voice → subs → video |
+| `ctx generate -t <topic> -f` | Force regenerate (overwrite existing) |
+| `ctx batch <file.json>` | Batch generate from JSON array of topics |
+| `ctx script -t <topic>` | Generate script only |
+| `ctx voice -s <script.txt>` | Generate voice only |
+| `ctx subs -a <audio.mp3>` | Generate subtitles only |
+| `ctx render -a <audio> -s <subs>` | Render video only |
+| `ctx voices` | List available voices |
+| `ctx setup` | First-time dependency setup |
+
+## 📄 License
+
+MIT — by [cecamarty](https://github.com/cecamarty)

package/bin/ctx.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import dotenv from 'dotenv';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+
+import { generateScript } from '../src/modules/script.js';
+import { generateVoice } from '../src/modules/voice.js';
+import { generateSubs } from '../src/modules/subs.js';
+import { renderReel } from '../src/modules/engine.js';
+import { runPipeline, runBatchPipeline } from '../src/modules/pipeline.js';
+
+// Load environment variables
+dotenv.config();
+
+const program = new Command();
+
+program
+    .name('ctx')
+    .description('Content Transformation eXecutor - CLI for automated faceless AI video generation')
+    .version('1.0.0');
+
+// Generate Command (Full Pipeline)
+program
+    .command('generate')
+    .description('Generate a full reel from a topic')
+    .requiredOption('-t, --topic <topic>', 'Topic to generate the script and reel about')
+    .option('--script-file <path>', 'Path to an existing script file to skip generation')
+    .option('--skip-subs', 'Skip subtitle generation and rendering', false)
+    .option('-f, --force', 'Force overwrite existing files', false)
+    .action(async (options) => {
+        await runPipeline(options.topic, {
+            skipSubs: options.skipSubs,
+            scriptPath: options.scriptFile,
+            force: options.force
+        });
+    });
+
+// Batch Command
+program
+    .command('batch')
+    .description('Batch generate reels from a JSON file of topics')
+    .argument('<inputFile>', 'JSON file containing an array of topics')
+    .option('--skip-subs', 'Skip subtitle generation and rendering', false)
+    .option('-f, --force', 'Force overwrite existing files', false)
+    .action(async (inputFile, options) => {
+        try {
+            const fullPath = path.resolve(inputFile);
+            if (!fs.existsSync(fullPath)) {
+                console.error(chalk.red(`[Batch] Error: File not found at ${fullPath}`));
+                process.exit(1);
+            }
+            const data = fs.readFileSync(fullPath, 'utf8');
+            const topics = JSON.parse(data);
+            if (!Array.isArray(topics)) {
+                console.error(chalk.red(`[Batch] Error: JSON file must contain an array of strings (topics).`));
+                process.exit(1);
+            }
+            await runBatchPipeline(topics, {
+                skipSubs: options.skipSubs,
+                force: options.force
+            });
+        } catch (err) {
+            console.error(chalk.red(`[Batch] Error reading or parsing file: ${err.message}`));
+        }
+    });
+
+// Script-Only Command
+program
+    .command('script')
+    .description('Generate script only')
+    .requiredOption('-t, --topic <topic>', 'Topic to generate the script about')
+    .action(async (options) => {
+        console.log(chalk.blue(`Generating script for topic: "${options.topic}"`));
+        await generateScript(options.topic);
+    });
+
+// Voice-Only Command
+program
+    .command('voice')
+    .description('Generate audio only from a script file')
+    .requiredOption('-s, --script <scriptFile>', 'Path to script text file')
+    .action(async (options) => {
+        await generateVoice(options.script);
+    });
+
+// Subs-Only Command
+program
+    .command('subs')
+    .description('Generate subtitles only from an audio file')
+    .requiredOption('-a, --audio <audioFile>', 'Path to audio file (MP3)')
+    .action(async (options) => {
+        await generateSubs(options.audio);
+    });
+
+// Render-Only Command
+program
+    .command('render')
+    .description('Render a reel from existing audio and optionally subtitles')
+    .requiredOption('-a, --audio <audioFile>', 'Path to generated audio (MP3)')
+    .option('-s, --subs <subsFile>', 'Path to generated subtitles (SRT or ASS)')
+    .action(async (options) => {
+        await renderReel(options.audio, options.subs);
+    });
+
+// Setup Command
+program
+    .command('setup')
+    .description('Run first-time setup: check dependencies, create Python venv, install faster-whisper')
+    .action(async () => {
+        const { exec } = await import('child_process');
+        const { promisify } = await import('util');
+        const { fileURLToPath } = await import('url');
+        const execPromise = promisify(exec);
+
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const setupScript = path.resolve(__dirname, '../scripts/setup.sh');
+
+        if (!fs.existsSync(setupScript)) {
+            console.error(chalk.red('[Setup] Error: setup.sh not found. Reinstall ctx-reels.'));
+            return;
+        }
+
+        try {
+            const { stdout, stderr } = await execPromise(`bash "${setupScript}"`, { stdio: 'inherit' });
+            if (stdout) console.log(stdout);
+            if (stderr) console.log(stderr);
+        } catch (err) {
+            console.error(chalk.red(`[Setup] Error: ${err.message}`));
+        }
+    });
+
+// Voices Command
+program
+    .command('voices')
+    .description('List available voices for the current engine')
+    .action(async () => {
+        const engine = process.env.VOICE_ENGINE || 'edge-tts';
+        console.log(chalk.blue(`\nVoice Engine: ${engine}\n`));
+
+        if (engine === 'kokoro') {
+            console.log(chalk.white('Available Kokoro voices:'));
+            const voices = [
+                'af_heart  - American Female (Heart) ⭐ Default',
+                'af_bella  - American Female (Bella)',
+                'af_sarah  - American Female (Sarah)',
+                'af_nicole - American Female (Nicole)',
+                'am_adam   - American Male (Adam)',
+                'am_michael - American Male (Michael)',
+                'bf_emma   - British Female (Emma)',
+                'bf_isabella - British Female (Isabella)',
+                'bm_george - British Male (George)',
+                'bm_lewis  - British Male (Lewis)',
+            ];
+            voices.forEach(v => console.log(`  ${v}`));
+            console.log(chalk.gray('\nSet voice: KOKORO_VOICE=af_bella in .env'));
+        } else if (engine === 'edge-tts') {
+            console.log(chalk.white('Run this to see all Edge-TTS voices:'));
+            console.log(chalk.gray('  edge-tts --list-voices | grep en-US'));
+            console.log(chalk.gray('\nSet voice: EDGE_TTS_VOICE=en-US-JennyNeural in .env'));
+        } else if (engine === 'elevenlabs') {
+            console.log(chalk.white('ElevenLabs voices are configured by voice ID.'));
+            console.log(chalk.gray('Browse: https://elevenlabs.io/voice-library'));
+            console.log(chalk.gray('\nSet voice: ELEVENLABS_VOICE_ID=<id> in .env'));
+        }
+        console.log('');
+    });
+
+program.parse();

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "ctx-reels",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "AI-powered faceless short-form video generator. Create TikTok/Reels/Shorts from a topic in one command.",
+  "main": "src/modules/pipeline.js",
+  "bin": {
+    "ctx": "./bin/ctx.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "scripts/",
+    ".env.example",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "setup": "bash scripts/setup.sh"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "tts",
+    "video",
+    "reels",
+    "shorts",
+    "tiktok",
+    "ai",
+    "faceless",
+    "content",
+    "kokoro",
+    "ffmpeg",
+    "text-to-speech"
+  ],
+  "author": "cecamarty",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cecamarty/ctx.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@elevenlabs/elevenlabs-js": "^2.36.0",
+    "@google/genai": "^1.42.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1",
+    "fluent-ffmpeg": "^2.1.3",
+    "kokoro-js": "^1.2.1"
+  }
+}

package/scripts/setup.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# CTX-Reels Setup Script
+# Run: ctx setup  OR  bash scripts/setup.sh
+
+set -e
+
+echo "🎬 CTX-Reels Setup"
+echo "=================="
+echo ""
+
+# 1. Check Node.js
+if ! command -v node &> /dev/null; then
+    echo "❌ Node.js not found. Please install Node.js >= 18"
+    exit 1
+fi
+echo "✅ Node.js $(node -v)"
+
+# 2. Check FFmpeg
+if command -v ffmpeg &> /dev/null; then
+    echo "✅ FFmpeg found: $(which ffmpeg)"
+elif [ -f "/usr/local/bin/ffmpeg" ]; then
+    echo "✅ FFmpeg found: /usr/local/bin/ffmpeg"
+else
+    echo "⚠️  FFmpeg not found. Please install it:"
+    echo "   macOS: brew install ffmpeg"
+    echo "   Linux: sudo apt install ffmpeg"
+    echo "   Windows: https://ffmpeg.org/download.html"
+fi
+
+# 3. Check FFprobe
+if command -v ffprobe &> /dev/null; then
+    echo "✅ FFprobe found: $(which ffprobe)"
+elif [ -f "/usr/local/bin/ffprobe" ]; then
+    echo "✅ FFprobe found: /usr/local/bin/ffprobe"
+else
+    echo "⚠️  FFprobe not found. Install with FFmpeg."
+fi
+
+# 4. Check Python3
+if command -v python3 &> /dev/null; then
+    echo "✅ Python3 found: $(python3 --version)"
+else
+    echo "⚠️  Python3 not found. Subtitles (faster-whisper) require Python 3."
+    echo "   Install: https://www.python.org/downloads/"
+fi
+
+# 5. Setup Python venv + faster-whisper
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+VENV_DIR="$PROJECT_DIR/.venv"
+
+if [ ! -d "$VENV_DIR" ]; then
+    echo ""
+    echo "📦 Creating Python virtual environment..."
+    python3 -m venv "$VENV_DIR"
+fi
+
+echo "📦 Installing faster-whisper..."
+"$VENV_DIR/bin/pip" install -q faster-whisper
+echo "✅ faster-whisper installed"
+
+# 6. Create .env if not exists
+ENV_FILE="$PROJECT_DIR/.env"
+ENV_EXAMPLE="$PROJECT_DIR/.env.example"
+if [ ! -f "$ENV_FILE" ] && [ -f "$ENV_EXAMPLE" ]; then
+    cp "$ENV_EXAMPLE" "$ENV_FILE"
+    echo "✅ Created .env from .env.example — edit it to add your GEMINI_API_KEY"
+elif [ -f "$ENV_FILE" ]; then
+    echo "✅ .env already exists"
+fi
+
+echo ""
+echo "🎉 Setup complete! Get started:"
+echo "   ctx generate -t \"Your Topic Here\""
+echo ""
+echo "   Output will be saved to: ~/Desktop/ctx/"
+echo "   Change output dir: set CTX_OUTPUT in .env"

package/src/modules/engine.js

@@ -0,0 +1,194 @@
+import ffmpeg from 'fluent-ffmpeg';
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { DIRS, ensureDirectories } from '../utils/fileConfig.js';
+import dotenv from 'dotenv';
+dotenv.config();
+
+/**
+ * Escapes a path for the FFmpeg subtitles filter.
+ */
+function escapePathsForSubtitlesFilter(srtPath) {
+    // Replace backslashes with escaped forward slashes or double backslashes,
+    // and escape colons if present (Windows paths like C: usually need this, but Mac/Linux are fine).
+    // For safety, converting to absolute or relative Unix-style path.
+    let cleanPath = srtPath.replace(/\\/g, '/');
+    // Escape colons because FFmpeg filter syntax uses : as a delimiter
+    cleanPath = cleanPath.replace(/:/g, '\\:');
+    // Escape single quotes
+    cleanPath = cleanPath.replace(/'/g, "\\'");
+    return cleanPath;
+}
+
+/**
+ * Generates the final reel using FFmpeg.
+ * @param {string} audioPath The path to the generated audio (MP3).
+ * @param {string} subsPath The path to the generated subtitles (SRT).
+ * @param {Array} assets List of B-roll assets to overlay.
+ * @returns {Promise<string|null>} The path to the final rendered reel (MP4), or null on error.
+ */
+export async function renderReel(audioPath, subsPath) {
+    return new Promise((resolve, reject) => {
+        try {
+            ensureDirectories();
+
+            if (!fs.existsSync(audioPath)) {
+                console.error(chalk.red(`[Engine] Error: Audio file not found at ${audioPath}`));
+                return resolve(null);
+            }
+            const hasSubs = subsPath && fs.existsSync(subsPath);
+
+            // 1. Determine Background Asset
+            let bgAsset = process.env.BG_ASSET || './templates/bg.jpg';
+
+            // If BG_ASSET is a directory, pick a random file from it
+            if (fs.existsSync(bgAsset) && fs.statSync(bgAsset).isDirectory()) {
+                const files = fs.readdirSync(bgAsset).filter(f =>
+                    ['.jpg', '.jpeg', '.png', '.mp4'].includes(path.extname(f).toLowerCase())
+                );
+                if (files.length > 0) {
+                    const randomFile = files[Math.floor(Math.random() * files.length)];
+                    bgAsset = path.join(bgAsset, randomFile);
+                    console.log(chalk.gray(`[Engine] Randomly selected background: ${randomFile}`));
+                } else {
+                    console.warn(chalk.yellow(`[Engine] Warning: Background directory ${bgAsset} is empty. Using default.`));
+                    bgAsset = './templates/bg.jpg';
+                }
+            }
+
+            if (!fs.existsSync(bgAsset)) {
+                console.error(chalk.red(`[Engine] Error: Background asset not found at ${bgAsset}.`));
+                return resolve(null);
+            }
+
+            const audioBasename = path.basename(audioPath, '.mp3');
+            const outputPath = path.join(DIRS.REELS, `${audioBasename}.mp4`);
+
+            console.log(chalk.blue(`[Engine] Rendering reel for: "${audioBasename}"...`));
+
+            // 1. Get Audio Duration to prevent hangs
+            const ffprobePath = process.env.FFPROBE_PATH || './lib/ffprobe';
+            ffmpeg.setFfprobePath(ffprobePath);
+            if (process.env.FFMPEG_PATH) {
+                ffmpeg.setFfmpegPath(process.env.FFMPEG_PATH);
+            }
+
+            ffmpeg.ffprobe(audioPath, (err, metadata) => {
+                if (err) {
+                    console.error(chalk.yellow(`[Engine] Warning: Could not probe audio duration. -shortest may hang.`));
+                }
+                const duration = metadata?.format?.duration;
+                const audioInputIndex = 1;
+
+                const command = ffmpeg();
+
+                // Inputs
+                if (bgAsset.toLowerCase().endsWith('.mp4')) {
+                    command.input(bgAsset).inputOptions('-stream_loop', '-1');
+                } else {
+                    command.input(bgAsset).loop();
+                }
+                command.input(audioPath);
+
+                const complexFilters = [];
+                // Base background processing
+                complexFilters.push({
+                    filter: 'scale',
+                    options: '1080:1920:force_original_aspect_ratio=increase',
+                    inputs: '0:v',
+                    outputs: 'bg'
+                });
+                complexFilters.push({
+                    filter: 'crop',
+                    options: '1080:1920',
+                    inputs: 'bg',
+                    outputs: 'vbase'
+                });
+
+                let lastOutput = 'vbase';
+
+                // Subtitles
+                let finalVideoOutput = lastOutput;
+                if (hasSubs) {
+                    const escapedSubsPath = escapePathsForSubtitlesFilter(path.resolve(subsPath));
+                    const isASS = subsPath.toLowerCase().endsWith('.ass');
+
+                    if (isASS) {
+                        // ASS files carry their own styling (karaoke, colors, fonts)
+                        complexFilters.push({
+                            filter: 'ass',
+                            options: escapedSubsPath,
+                            inputs: lastOutput,
+                            outputs: 'vfinal'
+                        });
+                    } else {
+                        // SRT fallback with force_style
+                        const fontName = process.env.SUB_FONT || 'Impact';
+                        const fontSize = process.env.SUB_SIZE || '28';
+                        const style = [
+                            `FontName=${fontName}`,
+                            `FontSize=${fontSize}`,
+                            `PrimaryColour=${process.env.SUB_COLOR || '&H0000FFFF'}`,
+                            `OutlineColour=${process.env.SUB_OUTLINE_COLOR || '&H00000000'}`,
+                            `BackColour=${process.env.SUB_BG_COLOR || '&H80000000'}`,
+                            `BorderStyle=${process.env.SUB_BORDER_STYLE || '1'}`,
+                            `Outline=2`,
+                            `Shadow=1`,
+                            `Alignment=${process.env.SUB_ALIGNMENT || '10'}`,
+                            `MarginV=${process.env.SUB_MARGIN_V || '480'}`,
+                            `Bold=1`
+                        ].join(',');
+
+                        complexFilters.push({
+                            filter: 'subtitles',
+                            options: {
+                                filename: escapedSubsPath,
+                                force_style: style
+                            },
+                            inputs: lastOutput,
+                            outputs: 'vfinal'
+                        });
+                    }
+                    finalVideoOutput = 'vfinal';
+                }
+
+                const outputOptions = [
+                    '-c:v libx264',
+                    '-preset veryfast', // Faster rendering
+                    '-c:a aac',
+                    '-b:a 192k',
+                    '-pix_fmt yuv420p',
+                    '-map', `${audioInputIndex}:a`, // Explicitly map audio
+                    '-shortest'
+                ];
+
+                if (duration) {
+                    outputOptions.push('-t', duration); // Hard limit to prevent hangs
+                }
+
+                command
+                    .complexFilter(complexFilters, finalVideoOutput)
+                    .outputOptions(outputOptions)
+                    .save(outputPath)
+                    .on('start', (cmd) => console.log(chalk.gray(`[Engine] Running FFmpeg...`)))
+                    .on('progress', (p) => {
+                        if (p.percent) process.stdout.write(`\r[Engine] Progress: ${p.percent.toFixed(1)}%`);
+                    })
+                    .on('end', () => {
+                        console.log(chalk.green(`\n[Engine] Success: ${outputPath}`));
+                        resolve(outputPath);
+                    })
+                    .on('error', (err, stdout, stderr) => {
+                        console.error(chalk.red(`\n[Engine] Error: ${err.message}`));
+                        console.error(chalk.yellow(stderr));
+                        resolve(null);
+                    });
+            });
+
+        } catch (error) {
+            console.error(chalk.red(`[Engine] General Error: ${error.message}`));
+            resolve(null);
+        }
+    });
+}