--- name: bggg-tiktok-readvideo description: > 把 TikTok、Reels、YouTube Shorts、UGC 广告、本地 MP4/MOV/WebM 等视频拆成 Codex 可读的视频上下文。 当用户要求 Codex 看懂视频、读视频、分析视频、总结视频、找 hook、找爆点、提取字幕、 语音转文字、ASR、批量转写 TikTok 视频或音频、 生成视频 timeline、抽关键帧、做 contact sheet、分析口播/画面/节奏、制定 TikTok 9:16 剪辑方案、 或把原始视频素材变成 edit_plan.json 并用 FFmpeg 渲染短视频时，应该使用此 skill。 本 skill 独立内置 ffprobe/ffmpeg/whisper.cpp/tesseract 可选流程，不依赖其他 BGGG skills。 ---

# BGGG TikTok ReadVideo

这个 skill 的原则很简单：不要让 Codex 直接“看 mp4”。先把视频拆成可读、可搜索、可执行的上下文，再让 Codex 做判断、剪辑规划和渲染。

核心脚本：

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

只需要转写音轨时使用独立转写脚本：

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

脚本会创建：

```text 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:

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

Give the run a stable project name:

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

Faster visual-only pass:

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

Use a specific whisper.cpp model:

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

Scene detection tuning:

```bash 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:

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

Batch transcribe a folder:

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

Generate subtitles and JSON too:

```bash 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:

```json { "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:

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

Validate without rendering:

```bash 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.

--- name: bggg-tiktok-readvideo description: > 把 TikTok、Reels、YouTube Shorts、UGC 广告、本地 MP4/MOV/WebM 等视频拆成 Codex 可读的视频上下文。 当用户要求 Codex 看懂视频、读视频、分析视频、总结视频、找 hook、找爆点、提取字幕、 语音转文字、ASR、批量转写 TikTok 视频或音频、 生成视频 timeline、抽关键帧、做 contact sheet、分析口播/画面/节奏、制定 TikTok 9:16 剪辑方案、 或把原始视频素材变成 edit_plan.json 并用 FFmpeg 渲染短视频时，应该使用此 skill。 本 skill 独立内置 ffprobe/ffmpeg/whisper.cpp/tesseract 可选流程，不依赖其他 BGGG skills。 ---

# BGGG TikTok ReadVideo

这个 skill 的原则很简单：不要让 Codex 直接“看 mp4”。先把视频拆成可读、可搜索、可执行的上下文，再让 Codex 做判断、剪辑规划和渲染。

核心脚本：

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

只需要转写音轨时使用独立转写脚本：

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

脚本会创建：

```text 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:

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

Give the run a stable project name:

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

Faster visual-only pass:

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

Use a specific whisper.cpp model:

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

Scene detection tuning:

```bash 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:

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

Batch transcribe a folder:

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

Generate subtitles and JSON too:

```bash 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:

```json { "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:

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

Validate without rendering:

```bash 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.

--- name: bggg-tiktok-readvideo description: > 把 TikTok、Reels、YouTube Shorts、UGC 广告、本地 MP4/MOV/WebM 等视频拆成 Codex 可读的视频上下文。 当用户要求 Codex 看懂视频、读视频、分析视频、总结视频、找 hook、找爆点、提取字幕、 语音转文字、ASR、批量转写 TikTok 视频或音频、 生成视频 timeline、抽关键帧、做 contact sheet、分析口播/画面/节奏、制定 TikTok 9:16 剪辑方案、 或把原始视频素材变成 edit_plan.json 并用 FFmpeg 渲染短视频时，应该使用此 skill。 本 skill 独立内置 ffprobe/ffmpeg/whisper.cpp/tesseract 可选流程，不依赖其他 BGGG skills。 ---

# BGGG TikTok ReadVideo

这个 skill 的原则很简单：不要让 Codex 直接“看 mp4”。先把视频拆成可读、可搜索、可执行的上下文，再让 Codex 做判断、剪辑规划和渲染。

核心脚本：

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

只需要转写音轨时使用独立转写脚本：

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

脚本会创建：

```text 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:

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

Give the run a stable project name:

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

Faster visual-only pass:

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

Use a specific whisper.cpp model:

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

Scene detection tuning:

```bash 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:

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

Batch transcribe a folder:

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

Generate subtitles and JSON too:

```bash 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:

```json { "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:

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

Validate without rendering:

```bash 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.

--- name: bggg-tiktok-readvideo description: > 把 TikTok、Reels、YouTube Shorts、UGC 广告、本地 MP4/MOV/WebM 等视频拆成 Codex 可读的视频上下文。 当用户要求 Codex 看懂视频、读视频、分析视频、总结视频、找 hook、找爆点、提取字幕、 语音转文字、ASR、批量转写 TikTok 视频或音频、 生成视频 timeline、抽关键帧、做 contact sheet、分析口播/画面/节奏、制定 TikTok 9:16 剪辑方案、 或把原始视频素材变成 edit_plan.json 并用 FFmpeg 渲染短视频时，应该使用此 skill。 本 skill 独立内置 ffprobe/ffmpeg/whisper.cpp/tesseract 可选流程，不依赖其他 BGGG skills。 ---

# BGGG TikTok ReadVideo

这个 skill 的原则很简单：不要让 Codex 直接“看 mp4”。先把视频拆成可读、可搜索、可执行的上下文，再让 Codex 做判断、剪辑规划和渲染。

核心脚本：

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

只需要转写音轨时使用独立转写脚本：

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

脚本会创建：

```text 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:

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

Give the run a stable project name:

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

Faster visual-only pass:

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

Use a specific whisper.cpp model:

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

Scene detection tuning:

```bash 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:

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

Batch transcribe a folder:

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

Generate subtitles and JSON too:

```bash 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:

```json { "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:

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

Validate without rendering:

```bash 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.