ctx-reels 1.0.0

package/src/modules/pipeline.js

@@ -0,0 +1,96 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { generateScript } from './script.js';
+import { generateVoice } from './voice.js';
+import { generateSubs } from './subs.js';
+import { renderReel } from './engine.js';
+import { slugify, DIRS } from '../utils/fileConfig.js';
+
+/**
+ * Runs the complete generation pipeline for a single topic.
+ * @param {string} topic The topic to generate a reel for.
+ * @param {object} options Configuration options (e.g., skipSubs)
+ */
+export async function runPipeline(topic, options = {}) {
+    const startTime = Date.now();
+    const slug = slugify(topic);
+    console.log(chalk.magenta.bold(`\n=== Starting CTX Pipeline for topic: "${topic}" ===\n`));
+
+    // 1. Script Generation
+    let scriptPath = options.scriptPath || path.join(DIRS.SCRIPTS, `${slug}.txt`);
+
+    if (options.scriptPath) {
+        console.log(chalk.yellow(`[Pipeline] Using explicit script file: ${scriptPath}`));
+    } else if (!options.force && fs.existsSync(scriptPath) && fs.statSync(scriptPath).size > 0) {
+        console.log(chalk.yellow(`[Pipeline] Skipping Script: Existing file found at ${scriptPath}`));
+    } else {
+        const generatedScript = await generateScript(topic);
+        if (!generatedScript) {
+            console.error(chalk.red('\n[Pipeline] Aborting: Failed at Script generation stage.'));
+            return false;
+        }
+        scriptPath = generatedScript;
+    }
+
+    // 2. Voice Generation
+    let audioPath = path.join(DIRS.AUDIO, `${slug}.mp3`);
+    if (!options.force && fs.existsSync(audioPath) && fs.statSync(audioPath).size > 0) {
+        console.log(chalk.yellow(`[Pipeline] Skipping Voice: Existing file found at ${audioPath}`));
+    } else {
+        const generatedAudio = await generateVoice(scriptPath);
+        if (!generatedAudio) {
+            console.error(chalk.red('\n[Pipeline] Aborting: Failed at Voice generation stage.'));
+            return false;
+        }
+        audioPath = generatedAudio;
+    }
+
+    // 3. Subtitles Generation (Optional)
+    let subsPath = path.join(DIRS.SUBTITLES, `${slug}.ass`);
+    if (options.skipSubs) {
+        console.log(chalk.yellow(`[Pipeline] Skipping subtitles as requested.`));
+        subsPath = null;
+    } else if (!options.force && fs.existsSync(subsPath) && fs.statSync(subsPath).size > 0) {
+        console.log(chalk.yellow(`[Pipeline] Skipping Subtitles: Existing file found at ${subsPath}`));
+    } else {
+        const generatedSubs = await generateSubs(audioPath);
+        if (!generatedSubs) {
+            console.error(chalk.red('\n[Pipeline] Aborting: Failed at Subtitles generation stage.'));
+            return false;
+        }
+        subsPath = generatedSubs;
+    }
+
+    // 4. Video Rendering
+    const reelPath = await renderReel(audioPath, subsPath);
+    if (!reelPath) {
+        console.error(chalk.red('\n[Pipeline] Aborting: Failed at Engine rendering stage.'));
+        return false;
+    }
+
+    const durationMs = Date.now() - startTime;
+    console.log(chalk.green.bold(`\n=== CTX Pipeline Completed in ${(durationMs / 1000).toFixed(1)}s ===`));
+    console.log(chalk.green(`Final Output: ${reelPath}\n`));
+    return true;
+}
+
+/**
+ * Runs the pipeline for a batch array of topics.
+ * @param {string[]} topics Array of topics
+ * @param {object} options Configuration options
+ */
+export async function runBatchPipeline(topics, options = {}) {
+    console.log(chalk.magenta.bold(`\n=== Starting Batch Pipeline for ${topics.length} topics ===\n`));
+    let successCount = 0;
+
+    // Running sequentially for Phase 1 MVP stability 
+    for (let i = 0; i < topics.length; i++) {
+        console.log(chalk.cyan(`\n--- Batch Item ${i + 1}/${topics.length} ---`));
+        const success = await runPipeline(topics[i], options);
+        if (success) successCount++;
+    }
+
+    console.log(chalk.magenta.bold(`\n=== Batch Pipeline Finished ===`));
+    console.log(chalk.magenta(`Successfully completed ${successCount} out of ${topics.length} reels.\n`));
+}

package/src/modules/script.js

@@ -0,0 +1,70 @@
+import { GoogleGenAI } from '@google/genai';
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { slugify, DIRS, ensureDirectories } from '../utils/fileConfig.js';
+import dotenv from 'dotenv';
+dotenv.config();
+
+/**
+ * Generates a short-form video script based on a given topic using the Gemini API.
+ * @param {string} topic The topic to write about.
+ * @returns {Promise<string|null>} The path to the generated script, or null on error.
+ */
+export async function generateScript(topic) {
+    try {
+        ensureDirectories();
+
+        const apiKey = process.env.GEMINI_API_KEY;
+        if (!apiKey) {
+            console.error(chalk.red('\n[Error] GEMINI_API_KEY is missing in .env. Please set it before running the script generator.'));
+            return null;
+        }
+
+        const ai = new GoogleGenAI({ apiKey });
+
+        console.log(chalk.blue(`[Script] Generating script for topic: "${topic}"...`));
+
+        const prompt = `You are a world-class viral scriptwriter for TikTok, Instagram Reels, and YouTube Shorts. 
+Your specialty is high-retention, fast-paced storytelling that GRABS attention in the first 2 seconds.
+
+Write a compelling 45-60 second spoken script about: "${topic}"
+
+STRUCTURE & STYLE:
+1. THE HOOK: Start with an "I can't believe this" or "Did you know" style statement that creates immediate curiosity. No generic intros like "Welcome back" or "Today we're talking about". Jump straight into the action.
+2. THE PUNCHY FACT: Follow the hook with a shocking or counter-intuitive fact. 
+3. THE NARRATIVE: Build the middle of the script using short, punchy sentences. Avoid flowery language. Use "power words" (e.g., 'Insane', 'Secret', 'Massive', 'Failure', 'Genius').
+4. THE LOOP/CTA: End with a thought-provoking question or a loop-ready statement that flows naturally back to the hook.
+
+CRITICAL CONSTRAINTS:
+- ONLY output the spoken text. 
+- NO markdown, NO bolding, NO emojis, NO technical instructions like "(pause)" or "[Visual]".
+- NO labels like "Hook:" or "Outro:".
+- The output must be one single, clean block of naturally spoken text.
+- Approximately 130-150 words total.`;
+
+        const response = await ai.models.generateContent({
+            model: process.env.GEMINI_MODEL || 'gemini-3-flash-preview',
+            contents: prompt,
+        });
+
+        const scriptText = response.text;
+
+        if (!scriptText || scriptText.trim() === '') {
+            console.error(chalk.red('[Script] Error: Gemini returned an empty response.'));
+            return null;
+        }
+
+        const slug = slugify(topic);
+        const outputPath = path.join(DIRS.SCRIPTS, `${slug}.txt`);
+
+        fs.writeFileSync(outputPath, scriptText.trim());
+        console.log(chalk.green(`[Script] Script generated successfully and saved to ${outputPath}`));
+
+        return outputPath;
+
+    } catch (error) {
+        console.error(chalk.red(`[Script] Error generating script: ${error.message}`));
+        return null;
+    }
+}

package/src/modules/subs.js

@@ -0,0 +1,142 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { exec } from 'child_process';
+import util from 'util';
+import { fileURLToPath } from 'url';
+import { GoogleGenAI } from '@google/genai';
+import { DIRS, ensureDirectories } from '../utils/fileConfig.js';
+import dotenv from 'dotenv';
+dotenv.config();
+
+const execPromise = util.promisify(exec);
+
+// Get __dirname equivalent in ES modules
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Generates an SRT subtitle file from a given audio file.
+ * Defaults to Gemini API to avoid local dependency issues on this machine.
+ * 
+ * @param {string} audioPath The path to the generated audio (MP3).
+ * @returns {Promise<string|null>} The path to the generated subtitles (SRT), or null on error.
+ */
+export async function generateSubs(audioPath) {
+    try {
+        ensureDirectories();
+
+        if (!fs.existsSync(audioPath)) {
+            console.error(chalk.red(`[Subs] Error: Audio file not found at ${audioPath}`));
+            return null;
+        }
+
+        const audioBasename = path.basename(audioPath, '.mp3');
+        const outputPath = path.join(DIRS.SUBTITLES, `${audioBasename}.ass`);
+
+        // --- GEMINI IMPLEMENTATION (DISABLED) ---
+        // return await generateSubsGemini(audioPath, outputPath);
+
+        // --- PYTHON IMPLEMENTATION (ACTIVE) ---
+        // To switch back to python-based whisper, uncomment the line below and comment the gemini line above.
+        return await generateSubsPython(audioPath, outputPath);
+
+    } catch (error) {
+        if (error.message.includes('429') || error.message.includes('quota')) {
+            console.error(chalk.yellow(`\n[Subs] Rate limit hit. Please wait ~1 minute and try again.`));
+        }
+        console.error(chalk.red(`[Subs] Error generating subtitles: ${error.message}`));
+        return null;
+    }
+}
+
+/**
+ * Uses Gemini API for transcription.
+ */
+async function generateSubsGemini(audioPath, outputPath) {
+    const apiKey = process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+        console.error(chalk.red('\n[Subs] Error: GEMINI_API_KEY is missing in .env.'));
+        return null;
+    }
+
+    const ai = new GoogleGenAI({ apiKey });
+
+    console.log(chalk.blue(`[Subs] Transcribing audio with Gemini: "${path.basename(audioPath)}"...`));
+
+    const audioBuffer = fs.readFileSync(audioPath);
+    const base64Audio = audioBuffer.toString('base64');
+
+    const prompt = `Transcribe this audio file and output it in a valid SRT (SubRip Subtitle) format. 
+Ensure the timestamps are accurate and synchronized with the speech. 
+Only output the SRT text content, no other explanations.`;
+
+    const response = await ai.models.generateContent({
+        model: process.env.GEMINI_MODEL || 'gemini-3-flash-preview',
+        contents: [
+            { text: prompt },
+            {
+                inlineData: {
+                    data: base64Audio,
+                    mimeType: "audio/mp3"
+                }
+            }
+        ]
+    });
+
+    let srtText = response.text;
+
+    // Clean up markdown code blocks if the AI includes them
+    srtText = srtText.replace(/```srt\n?|```/g, '').trim();
+
+    if (!srtText || srtText.length < 10) {
+        console.error(chalk.red('[Subs] Error: Gemini returned an invalid SRT.'));
+        return null;
+    }
+
+    fs.writeFileSync(outputPath, srtText);
+    console.log(chalk.green(`[Subs] Subtitles generated via Gemini and saved to ${outputPath}`));
+
+    return outputPath;
+}
+
+/**
+ * Uses local Python script (faster-whisper) for transcription.
+ * (Preserved for when dependencies are fixed)
+ */
+async function generateSubsPython(audioPath, outputPath) {
+    const pythonScriptPath = path.resolve(__dirname, '../python/whisper_runner.py');
+
+    if (!fs.existsSync(pythonScriptPath)) {
+        console.error(chalk.red(`[Subs] Error: Python script not found at ${pythonScriptPath}`));
+        return null;
+    }
+
+    const audioBasename = path.basename(audioPath, '.mp3');
+    console.log(chalk.blue(`[Subs] Generating subtitles for audio: "${audioBasename}" (Python)...`));
+
+    // Portable Python detection: env var > local .venv > python3 on PATH
+    let pythonBin = process.env.PYTHON_PATH;
+    if (!pythonBin) {
+        const venvPythonPath = path.resolve(__dirname, '../../.venv/bin/python');
+        if (fs.existsSync(venvPythonPath)) {
+            pythonBin = venvPythonPath;
+        } else {
+            pythonBin = 'python3';
+        }
+    }
+    const command = `${pythonBin} "${pythonScriptPath}" --audio "${audioPath}" --output "${outputPath}" --format ass`;
+    const { stdout, stderr } = await execPromise(command);
+
+    if (stderr && stderr.trim().length > 0) {
+        console.warn(chalk.yellow(`[Subs] Python Output (stderr): ${stderr}`));
+    }
+
+    if (!fs.existsSync(outputPath)) {
+        console.error(chalk.red(`[Subs] Error: Python script finished but SRT file wasn't created.`));
+        return null;
+    }
+
+    console.log(chalk.green(`[Subs] Subtitles generated successfully and saved to ${outputPath}`));
+    return outputPath;
+}

package/src/modules/voice.js

@@ -0,0 +1,211 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { exec } from 'child_process';
+import util from 'util';
+import ffmpeg from 'fluent-ffmpeg';
+import { DIRS, ensureDirectories } from '../utils/fileConfig.js';
+import dotenv from 'dotenv';
+dotenv.config();
+
+const execPromise = util.promisify(exec);
+
+/**
+ * Generates an audio file from a given script text file using edge-tts.
+ * @param {string} scriptPath The path to the generated script text file.
+ * @returns {Promise<string|null>} The path to the generated audio file, or null on error.
+ */
+export async function generateVoice(scriptPath) {
+    try {
+        ensureDirectories();
+
+        if (!fs.existsSync(scriptPath)) {
+            console.error(chalk.red(`[Voice] Error: Script file not found at ${scriptPath}`));
+            return null;
+        }
+
+        const scriptBasename = path.basename(scriptPath, '.txt');
+        const outputPath = path.join(DIRS.AUDIO, `${scriptBasename}.mp3`);
+
+        console.log(chalk.blue(`[Voice] Generating audio for script: "${scriptBasename}"...`));
+
+        // Read the script to log length or handle empty files
+        const scriptContent = fs.readFileSync(scriptPath, 'utf-8');
+        if (!scriptContent || scriptContent.trim() === '') {
+            console.error(chalk.red('[Voice] Error: Script is empty.'));
+            return null;
+        }
+
+        const engine = process.env.VOICE_ENGINE || 'edge-tts';
+
+        if (engine === 'elevenlabs' && process.env.ELEVENLABS_API_KEY && process.env.ELEVENLABS_API_KEY.trim() !== '') {
+            console.log(chalk.magenta(`[Voice] ELEVENLABS_API_KEY detected. Using ElevenLabs API...`));
+            try {
+                const { ElevenLabsClient } = await import('@elevenlabs/elevenlabs-js');
+                const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });
+
+                // Using 'Adam' as a default reliable voice, configurable later
+                const voiceId = process.env.ELEVENLABS_VOICE_ID || "pNInz6obpgDQGcFmaJcg";
+
+                const audioStream = await client.textToSpeech.convert(voiceId, {
+                    text: scriptContent,
+                    model_id: "eleven_multilingual_v2",
+                    output_format: "mp3_44100_128",
+                });
+
+                const writeStream = fs.createWriteStream(outputPath);
+                for await (const chunk of audioStream) {
+                    writeStream.write(chunk);
+                }
+                writeStream.end();
+
+                await new Promise((resolve) => writeStream.on('finish', resolve));
+
+            } catch (err) {
+                console.error(chalk.red(`[Voice] ElevenLabs API Error: ${err.message}`));
+                console.log(chalk.yellow(`[Voice] Falling back to Edge-TTS...`));
+                await generateWithEdgeTTS(scriptPath, outputPath);
+            }
+        } else if (engine === 'kokoro') {
+            try {
+                await generateWithKokoro(scriptContent, outputPath);
+            } catch (err) {
+                console.error(chalk.red(`[Voice] Kokoro Generation Error: ${err.message}`));
+                console.log(chalk.yellow(`[Voice] Falling back to Edge-TTS...`));
+                await generateWithEdgeTTS(scriptPath, outputPath);
+            }
+        } else {
+            await generateWithEdgeTTS(scriptPath, outputPath);
+        }
+
+        if (!fs.existsSync(outputPath)) {
+            console.error(chalk.red(`[Voice] Error: Audio file wasn't created at ${outputPath}`));
+            return null;
+        }
+
+        const stats = fs.statSync(outputPath);
+        if (stats.size === 0) {
+            console.error(chalk.red(`[Voice] Error: Generated audio file is 0 bytes.`));
+            return null;
+        }
+
+        console.log(chalk.blue(`[Voice] Trimming silence to make narration snappier...`));
+        const snappyPath = outputPath.replace('.mp3', '-snappy.mp3');
+
+        await new Promise((resolve, reject) => {
+            if (process.env.FFMPEG_PATH) ffmpeg.setFfmpegPath(process.env.FFMPEG_PATH);
+
+            ffmpeg(outputPath)
+                // Filter: removes pauses > 0.3s (gentle trim, preserves natural speech)
+                .audioFilters('silenceremove=stop_periods=-1:stop_duration=0.3:stop_threshold=-50dB')
+                .save(snappyPath)
+                .on('end', () => {
+                    fs.renameSync(snappyPath, outputPath);
+                    resolve();
+                })
+                .on('error', (err) => {
+                    console.warn(chalk.yellow(`[Voice] Warning: Silence trimming failed: ${err.message}`));
+                    resolve();
+                });
+        });
+
+        console.log(chalk.green(`[Voice] Audio generated & processed successfully: ${outputPath}`));
+        return outputPath;
+
+    } catch (error) {
+        console.error(chalk.red(`[Voice] Error generating voice: ${error.message}`));
+        return null;
+    }
+}
+
+async function generateWithEdgeTTS(scriptPath, outputPath) {
+    console.log(chalk.blue(`[Voice] Generating with Edge-TTS...`));
+    const voice = process.env.EDGE_TTS_VOICE || 'en-US-ChristopherNeural';
+    const command = `edge-tts --voice ${voice} --file "${scriptPath}" --write-media "${outputPath}"`;
+
+    const { stdout, stderr } = await execPromise(command);
+
+    if (stderr && stderr.trim().length > 0) {
+        console.warn(chalk.yellow(`[Voice] Edge-TTS CLI Output: ${stderr}`));
+    }
+}
+
+async function generateWithKokoro(scriptContent, outputPath) {
+    console.log(chalk.blue(`[Voice] Generating with Kokoro-JS...`));
+    const { KokoroTTS } = await import('kokoro-js');
+
+    const tts = await KokoroTTS.from_pretrained('onnx-community/Kokoro-82M-v1.0-ONNX', {
+        dtype: 'q8',
+    });
+    const voice = process.env.KOKORO_VOICE || 'af_heart';
+
+    // Split text into sentences to avoid Kokoro truncating long scripts
+    const sentences = scriptContent
+        .replace(/([.?!])\s+/g, '$1|SPLIT|')
+        .split('|SPLIT|')
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+
+    console.log(chalk.gray(`[Voice] Generating ${sentences.length} audio chunks...`));
+
+    const tempDir = path.dirname(outputPath);
+    const chunkPaths = [];
+
+    for (let i = 0; i < sentences.length; i++) {
+        const sentence = sentences[i];
+        const preview = sentence.length > 50 ? sentence.substring(0, 50) + '...' : sentence;
+        console.log(chalk.gray(`[Voice]   Chunk ${i + 1}/${sentences.length}: "${preview}"`));
+
+        const audio = await tts.generate(sentence, { voice });
+
+        const chunkRawPath = path.join(tempDir, `_chunk_${i}.raw`);
+        const chunkMp3Path = path.join(tempDir, `_chunk_${i}.mp3`);
+
+        // Write raw PCM
+        fs.writeFileSync(chunkRawPath, Buffer.from(audio.audio.buffer));
+
+        // Convert raw PCM to MP3
+        await new Promise((resolve, reject) => {
+            if (process.env.FFMPEG_PATH) ffmpeg.setFfmpegPath(process.env.FFMPEG_PATH);
+
+            ffmpeg()
+                .input(chunkRawPath)
+                .inputOptions(['-f', 'f32le', '-ar', '24000', '-ac', '1'])
+                .output(chunkMp3Path)
+                .audioBitrate('192k')
+                .on('end', () => {
+                    fs.unlinkSync(chunkRawPath);
+                    resolve();
+                })
+                .on('error', (err) => reject(err))
+                .run();
+        });
+
+        chunkPaths.push(chunkMp3Path);
+    }
+
+    // Concatenate all chunks using FFmpeg concat demuxer
+    const concatListPath = path.join(tempDir, '_concat_list.txt');
+    const concatContent = chunkPaths.map(p => `file '${p}'`).join('\n');
+    fs.writeFileSync(concatListPath, concatContent);
+
+    await new Promise((resolve, reject) => {
+        if (process.env.FFMPEG_PATH) ffmpeg.setFfmpegPath(process.env.FFMPEG_PATH);
+
+        ffmpeg()
+            .input(concatListPath)
+            .inputOptions(['-f', 'concat', '-safe', '0'])
+            .outputOptions(['-c', 'copy'])
+            .output(outputPath)
+            .on('end', () => {
+                // Cleanup temp files
+                chunkPaths.forEach(p => { try { fs.unlinkSync(p); } catch (e) { } });
+                try { fs.unlinkSync(concatListPath); } catch (e) { }
+                resolve();
+            })
+            .on('error', (err) => reject(err))
+            .run();
+    });
+
+    console.log(chalk.green(`[Voice] Kokoro: ${sentences.length} chunks concatenated successfully.`));
+}

package/src/python/whisper_runner.py

@@ -0,0 +1,139 @@
+import sys
+import os
+import argparse
+from typing import List
+from faster_whisper import WhisperModel
+
+def format_time_srt(seconds: float) -> str:
+    """Format time in seconds to SRT format (HH:MM:SS,mmm)."""
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    seconds_remainder = seconds % 60
+    return f"{hours:02d}:{minutes:02d}:{seconds_remainder:06.3f}".replace('.', ',')
+
+def format_time_ass(seconds: float) -> str:
+    """Format time in seconds to ASS format (H:MM:SS.cc)."""
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = seconds % 60
+    centiseconds = int((secs - int(secs)) * 100)
+    return f"{hours}:{minutes:02d}:{int(secs):02d}.{centiseconds:02d}"
+
+def chunk_words(words, max_words=4):
+    """Split a list of words into chunks of max_words."""
+    chunks = []
+    current_chunk = []
+    for word in words:
+        current_chunk.append(word)
+        if len(current_chunk) >= max_words:
+            chunks.append(current_chunk)
+            current_chunk = []
+    if current_chunk:
+        chunks.append(current_chunk)
+    return chunks
+
+def create_srt(segments: List, output_file: str):
+    """Write Faster-Whisper segments to an SRT file using word-level timestamps."""
+    counter = 1
+    with open(output_file, 'w', encoding='utf-8') as f:
+        for segment in segments:
+            if not segment.words:
+                # Fallback: use segment-level if no word timestamps
+                start_time = format_time_srt(segment.start)
+                end_time = format_time_srt(segment.end)
+                text = segment.text.strip()
+                f.write(f"{counter}\n")
+                f.write(f"{start_time} --> {end_time}\n")
+                f.write(f"{text}\n\n")
+                counter += 1
+                continue
+
+            chunks = chunk_words(segment.words, max_words=4)
+            for chunk in chunks:
+                start_time = format_time_srt(chunk[0].start)
+                end_time = format_time_srt(chunk[-1].end)
+                text = " ".join(w.word.strip() for w in chunk)
+                f.write(f"{counter}\n")
+                f.write(f"{start_time} --> {end_time}\n")
+                f.write(f"{text}\n\n")
+                counter += 1
+
+def create_ass(segments: List, output_file: str):
+    """Write ASS subtitle file with karaoke word-level highlighting.
+    
+    Base color: Yellow. Active word highlight: White.
+    Uses \\kf (smooth karaoke fill) tags for per-word timing.
+    """
+    header = """[Script Info]
+Title: CTX Karaoke Subtitles
+ScriptType: v4.00+
+PlayResX: 1080
+PlayResY: 1920
+WrapStyle: 0
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+Style: Default,Impact,38,&H0000FFFF,&H00FFFFFF,&H00000000,&H80000000,-1,0,0,0,100,100,0,0,1,2,1,5,10,10,480,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+"""
+    with open(output_file, 'w', encoding='utf-8') as f:
+        f.write(header)
+        
+        for segment in segments:
+            if not segment.words:
+                start = format_time_ass(segment.start)
+                end = format_time_ass(segment.end)
+                text = segment.text.strip()
+                f.write(f"Dialogue: 0,{start},{end},Default,,0,0,0,,{text}\n")
+                continue
+
+            chunks = chunk_words(segment.words, max_words=4)
+            
+            for chunk in chunks:
+                chunk_start = format_time_ass(chunk[0].start)
+                chunk_end = format_time_ass(chunk[-1].end)
+                
+                # Build karaoke text with \kf tags
+                # \kf<duration_in_centisecs> makes the word transition from secondary to primary color
+                karaoke_parts = []
+                for word in chunk:
+                    duration_cs = int((word.end - word.start) * 100)
+                    if duration_cs < 1:
+                        duration_cs = 1
+                    word_text = word.word.strip()
+                    karaoke_parts.append(f"{{\\kf{duration_cs}}}{word_text}")
+                
+                line = " ".join(karaoke_parts)
+                f.write(f"Dialogue: 0,{chunk_start},{chunk_end},Default,,0,0,0,,{line}\n")
+
+def transcribe(audio_path: str, output_path: str, model_size="base", output_format="ass"):
+    """Transcribe an audio file using faster-whisper."""
+    if not os.path.exists(audio_path):
+        print(f"Error: Audio file not found at {audio_path}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Loading faster-whisper model ({model_size})...")
+    model = WhisperModel(model_size, device="cpu", compute_type="int8")
+
+    print(f"Transcribing {audio_path}...")
+    segments, info = model.transcribe(audio_path, beam_size=5, word_timestamps=True)
+    segment_list = list(segments)
+    
+    if output_format == "ass":
+        create_ass(segment_list, output_path)
+    else:
+        create_srt(segment_list, output_path)
+    
+    print(f"Successfully generated {output_format.upper()} at {output_path}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Generate subtitles from audio using Faster-Whisper")
+    parser.add_argument("--audio", required=True, help="Path to the input audio file")
+    parser.add_argument("--output", required=True, help="Path to save the output subtitle file")
+    parser.add_argument("--model", default="base", help="Model size for Faster-Whisper (e.g., tiny, base, small)")
+    parser.add_argument("--format", default="ass", choices=["srt", "ass"], help="Output format: srt or ass")
+    
+    args = parser.parse_args()
+    transcribe(args.audio, args.output, args.model, args.format)