🎬 Video-MKT: Programmatic Video Creation & Marketing Automation

Video-MKT is a production-grade, agent-assisted pipeline designed to automate the creation, rendering, and publishing of short-form and long-form marketing videos. Built on top of HyperFrames (HTML/CSS/JS-based video composition), this repository combines AI scriptwriting, automatic Text-to-Speech (TTS), Whisper voice transcription, interactive rendering, and headless upload scheduling into a unified DevOps-like video production workflow.

• 🤖 Agent-Assisted Writing & Scaffold: Write structured Markdown scripts under projects/ and let AI agents bootstrap full video projects automatically.
• 🎙️ Advanced TTS & Word-by-Word Transcription: Supports high-quality Vietnamese/English voices (VieNeu & Supertonic) and auto-generates word-by-word timestamps using OpenAI Whisper.
• 🎨 HyperFrames Compositions: Design beautiful, high-performance HTML/CSS timelines powered by GSAP, Anime.js, and Three.js. Supports dynamic responsive layouts (vertical 1080x1920 for TikTok/Shorts and horizontal 1920x1080 for YouTube).
• 📂 Component Catalog & Templates: Standalone, reusable video clips (hook, CTA, mockup) under templates/blocks and HTML/CSS snippets under templates/components.
• 📊 Duplicate Prevention & History Tracker: Track published videos across channels (TikTok, YouTube, Facebook) using a centralized SQLite database (my-data/history.db) to avoid spamming algorithms.
• 🚀 Automated Uploading & Scheduling: Headless browser automation via a built-in submodule for direct scheduled uploads to TikTok.

Video-MKT/
├── .agents/                 # AI Agent instructions, rulebooks, and workflow guides
│   ├── rules/               # Specific design systems and voice guidelines per video topic
│   └── workflows/           # Standard operating procedures (e.g., create-video.md)
├── scripts/                 # Core utility and automation scripts
│   ├── scaffold.sh          # Orchestrates video bootstrapping (init -> TTS -> Whisper)
│   ├── history_manager.py   # Centralized publication database CLI
│   ├── vieneu_tts.py        # Vietnamese Voice cloning TTS client
│   └── supertonic_tts.py    # English/Multilingual TTS client
├── templates/               # Reusable UI Blocks and components
│   ├── blocks/              # Modular compositions (comms, transitions, headers)
│   └── components/          # Animation and styling snippets
├── projects/                # Video production workspace grouped by product/slug
│   └── <product-name>/      # e.g., ai-news, app-promo, debt-payoff-x
│       └── tiktok/          # Vertical format output NN_<slug> directories
└── tools/                   # External helper submodules
    └── TiktokAutoUploader   # Headless uploader fork (Puppeteer/undetected-chromedriver)

Clone this repository with submodules:

git clone --recursive <repository-url>
cd Video-MKT

Set up the Python virtual environment and install dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r scripts/requirements.txt

Install HyperFrames CLI globally or in your project:

npm install -g hyperframes
# or run via npx
npx hyperframes --help

Follow these five steps to create and render a new TikTok video:

Create a Markdown script under projects/<product>/tiktok/_scripts/NN_<slug>.md:

# TikTok Script NN: Awesome Tool

**Goal:** Drive signups
**Tone:** Energetic, Neo-brutalist

## Voiceover
"Check out this brand new open source tool that will save you hours of coding!"

Run the automated scaffolding script. For Vietnamese videos, set transcription variables:

PYTHONIOENCODING=utf-8 WHISPER_MODEL=small WHISPER_LANG=vi ./scripts/scaffold.sh projects/ai-news/tiktok/_scripts/01_example.md

This script:

1. Initializes a new HyperFrames directory.
2. Synthesizes narration.txt to narration.wav.
3. Runs Whisper to extract word-level timestamps to audio/transcript.json.

Develop your layout using standard HTML/CSS. Connect audio tracks and animations:

<audio id="narration" src="audio/narration.wav" data-start="0"></audio>
<div id="slide1" class="clip" data-start="0" data-duration="5">
  <h1>AWESOME TOOL</h1>
</div>

Launch the local dev server to review your video interactively:

npx hyperframes preview

Inspect for layout issues or layout shifts:

npx hyperframes inspect --samples 10

Export your production-grade video:

npx hyperframes render --output out/01_example.mp4

Manage your publication database with history_manager.py:

# Check if a video has been published before (returns exit code 1 if duplicate found)
python scripts/history_manager.py check -v out/my-video.mp4

# Log a successful publication
python scripts/history_manager.py log -v out/my-video.mp4 -t "My Video Title" -p tiktok -a itowf -s succeeded

# Check overall publishing statistics
python scripts/history_manager.py stats

• Keep layout dimensions fixed at 1080x1920 for vertical formats.
• Avoid exit animations unless it is the final CTA slide.
• Always use data-track-index layers properly to avoid asset overlapping conflicts.

This repository is licensed under the MIT License. See LICENSE for details.