bggg-tiktok-readvideo

BGGG TikTok ReadVideo

The principle of this skill is simple: do not let Codex directly "watch the mp4." First break the video into readable, searchable, actionable context, then let Codex make judgments, plan edits, and render.

Core script:

python3 bggg-tiktok-readvideo/scripts/analyze_video.py "/path/to/input.mp4"

When you only need to transcribe the audio track, use the standalone transcription script:

python3 bggg-tiktok-readvideo/scripts/transcribe_video.py "/path/to/video-or-folder" --recursive --srt

The script will create:

bggg-tiktok-readvideo/projects/YYYYMMDD_slug/
├── raw/input.mp4
├── analysis/
│   ├── metadata.json
│   ├── transcript.txt
│   ├── transcript.srt
│   ├── scenes.json
│   ├── timeline.md
│   ├── contact_sheet.jpg
│   ├── keyframes/
│   ├── audio_events.json
│   ├── ocr.json
│   └── analysis_manifest.json
└── output/
    └── edit_plan.template.json

Default Workflow

1. Run scripts/analyze_video.py before making any claim about the video content.
2. If the user only asks for transcription/ASR, run scripts/transcribe_video.py instead of the full visual analysis pipeline.
3. Read analysis/timeline.md, analysis/scenes.json, analysis/transcript.srt, analysis/audio_events.json, and analysis/ocr.json.
4. Inspect analysis/contact_sheet.jpg as the visual overview. Use individual analysis/keyframes/frame_XXXX.jpg when a scene needs closer visual reading.
5. If the user asks for TikTok editing, write output/edit_plan.json before rendering.
6. Render with scripts/render_tiktok.py only after the edit plan exists.

Do not infer content from the filename, title, or folder name alone. The timeline and contact sheet are the source of truth.

Analyze Commands

Basic local analysis:

python3 bggg-tiktok-readvideo/scripts/analyze_video.py "/path/to/video.mp4"

Give the run a stable project name:

python3 bggg-tiktok-readvideo/scripts/analyze_video.py "/path/to/video.mp4" \
  --slug product_qc_ugc

Faster visual-only pass:

python3 bggg-tiktok-readvideo/scripts/analyze_video.py "/path/to/video.mp4" \
  --no-transcribe --max-frames 24

Use a specific whisper.cpp model:

python3 bggg-tiktok-readvideo/scripts/analyze_video.py "/path/to/video.mp4" \
  --model small --language auto

Scene detection tuning:

python3 bggg-tiktok-readvideo/scripts/analyze_video.py "/path/to/video.mp4" \
  --scene-threshold 0.22 --min-scene-interval 0.8 --max-frames 48

Transcription Commands

The standalone transcription flow was merged from bggg-tiktok-whisper. It supports video/audio files, folders, recursive batch runs, skip-existing behavior, and a JSON manifest.

Transcribe one video or audio file:

python3 bggg-tiktok-readvideo/scripts/transcribe_video.py "/path/to/video.mp4"

Batch transcribe a folder:

python3 bggg-tiktok-readvideo/scripts/transcribe_video.py "/path/to/downloads" --recursive

Generate subtitles and JSON too:

python3 bggg-tiktok-readvideo/scripts/transcribe_video.py "/path/to/video.mp4" --srt --json

Outputs default to a transcripts/ folder beside the source file, or to --output-dir when provided. Existing .txt transcripts are skipped unless --force is set.

Reading The Output

Use the artifacts in this order:

1. analysis_manifest.json: paths and warnings from the run.
2. metadata.json: duration, resolution, audio/video streams, fps, codec.
3. contact_sheet.jpg: quick visual pass across scenes.
4. timeline.md: scene table with transcript excerpts and keyframe paths.
5. transcript.srt: exact spoken-word timestamps.
6. audio_events.json: silence and volume clues for pacing.
7. ocr.json: screen text if tesseract is installed; otherwise it records why OCR was skipped.

When summarizing or editing, cite timestamps such as 00:03.20-00:06.80.

TikTok Edit Planning

For TikTok / UGC / ad editing, create output/edit_plan.json with this structure:

{
  "source_video": "raw/input.mp4",
  "analysis_manifest": "analysis/analysis_manifest.json",
  "goal": "15-25s TikTok UGC edit for cross-border ecommerce",
  "output": "output/final_tiktok_9x16.mp4",
  "defaults": {
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "fit": "cover",
    "burn_captions": true,
    "caption_source_timeline": true
  },
  "segments": [
    {
      "start": 0.0,
      "end": 2.2,
      "label": "hook",
      "reason": "Strong curiosity opening"
    }
  ],
  "captions": [
    {
      "start": 0.0,
      "end": 2.2,
      "text": "I found the cheaper way to buy this"
    }
  ]
}

TikTok defaults:

• 9:16, 1080x1920, 30fps.
• Strong first 2 seconds.
• Remove dead air and repeated setup.
• Prefer proof shots: product close-up, QC photo, order screen, warehouse/packing, delivery proof.
• Keep captions short and readable; use the original language unless the user asks for translation.
• For cross-border ecommerce, look for trust points: QC, warehouse inspection, PayPal, tracking, shipping speed, real product comparison, price proof.

Render:

python3 bggg-tiktok-readvideo/scripts/render_tiktok.py \
  bggg-tiktok-readvideo/projects/YYYYMMDD_slug/output/edit_plan.json

Validate without rendering:

python3 bggg-tiktok-readvideo/scripts/render_tiktok.py \
  bggg-tiktok-readvideo/projects/YYYYMMDD_slug/output/edit_plan.json --dry-run

What Codex Should Decide

The script extracts context; Codex still owns judgment:

• Which scene is the strongest hook.
• Which claim needs visual proof.
• Which silent or low-value spans to remove.
• Where B-roll should support the transcript.
• Whether the output should be summary, edit plan, final rendered video, or reusable asset archive.

For deeper design notes, read:

• references/video-context-schema.md for artifact schemas.
• references/whisper-transcription.md for standalone and batch transcription details.
• references/whisper-merge-notes.md for the bggg-tiktok-whisper comparison and merge decision.
• references/tiktok-editing.md for TikTok editing heuristics.
• references/source-projects.md for what was copied from Popcorn and related video-understanding projects.