# Gnommo Feature Development Roadmap

## Overview
Features to standardize the Keynote-to-YouTube workflow, so that once the presentation is complete, only a standardized recording session stands between you and a finished video.

---

## 1. Video Description Generator

**Command:** `gnommo -p <project> description`

Generate a complete YouTube description with citations, attributions, and chapters.

---

### 1.1 Manuscript Citations (`[cite:...]`)

Citations embedded in the manuscript represent sources, references, or links mentioned during narration. The text after `cite:` is the **literal reference** that should appear in the description.

**Format in manuscript.txt:**
```
[cite:Reference text exactly as it should appear]
```

**Examples:**
```
[S3]
According to this study [cite:Smith et al. (2024) "Effects of AI on Productivity" - https://example.com/paper],
the effect is significant.

[S7]
I'm using [cite:Keynote by Apple - https://apple.com/keynote] for all my presentations.

[S12]
This technique was pioneered by [cite:Dr. Jane Doe, MIT Media Lab].
```

**Output in description:**
```
SOURCES & REFERENCES
━━━━━━━━━━━━━━━━━━━━
1:23 - Smith et al. (2024) "Effects of AI on Productivity" - https://example.com/paper
4:56 - Keynote by Apple - https://apple.com/keynote
8:30 - Dr. Jane Doe, MIT Media Lab
```

**Requirements:**
- Parse `[cite:...]` markers from manuscript.txt
- Extract the literal text after `cite:` as the reference
- Align citations to timestamps (same fuzzy matching as other markers)
- Group citations in order of appearance
- Citations are NOT aligned for rendering (ignored by renderer) but ARE timestamped for description

**Note:** `[cite:...]` markers should not affect video rendering or narration alignment - they are metadata-only markers for description generation.

---

### 1.2 Pexels/Stock Footage Attribution

Attribution for Pexels content is **not legally required** but is appreciated and professional.

**Official Pexels attribution format:**
```
by [Contributor Name] via Pexels
```

**Implementation:**
- Extend `videos.json` to include attribution metadata:
  ```json
  {
    "beach_waves": {
      "source_file": "pexels/beach.mp4",
      "is_shared": true,
      "attribution": {
        "source": "pexels",
        "creator": "John Doe",
        "url": "https://pexels.com/video/12345"
      }
    }
  }
  ```
- Auto-detect Pexels videos from `shared_assets/pexels/` folder
- Support Pexels metadata JSON files (if downloaded with video)
- Generate attribution section for video description:
  ```
  STOCK FOOTAGE
  ━━━━━━━━━━━━━
  Beach waves by John Doe via Pexels: https://pexels.com/video/12345
  City timelapse by Jane Smith via Pexels: https://pexels.com/video/67890
  ```

**Pexels License Notes** (from pexels.com/license):
- Free for personal and commercial use
- Attribution not required but appreciated
- Cannot sell unaltered copies
- Cannot redistribute on other stock platforms

### 1.3 Complete Description Output

**Output file:** `out/description_youtube.txt`

Combine all elements into a ready-to-paste YouTube description.

**Structure:**
```
[Video description from project.json "description" field]

CHAPTERS
━━━━━━━━
0:00 Introduction
1:23 Topic One
3:45 Topic Two
...

REFERENCES
━━━━━━━━━━
1:23 - Smith et al. (2024) "AI Study" - https://example.com
4:56 - Keynote by Apple - https://apple.com/keynote
...

STOCK FOOTAGE
━━━━━━━━━━━━━
Beach waves by John Doe via Pexels: https://pexels.com/video/12345
...

[Optional footer from project.json "footer" field - social links, subscribe CTA, etc.]
```

**project.json additions:**
```json
{
  "description": "In this video, I walk through the complete Gnommo workflow for creating YouTube videos from Keynote presentations.",
  "footer": "Subscribe for more tutorials: https://youtube.com/@channel\nTwitter: https://twitter.com/handle"
}
```

**Requirements:**
- Pull video description from `project.json` "description" field
- Generate chapters from slide markers (see Section 2)
- Collect all `[cite:...]` references with timestamps
- Collect all Pexels/stock attributions from `videos.json`
- Append optional footer from `project.json` "footer" field
- Output to `out/description_youtube.txt`
- Sections with no content are omitted (e.g., no STOCK FOOTAGE section if none used)

---

## 2. YouTube Chapter Markers

**Command:** `gnommo -p <project> chapters`

Auto-generate chapter timestamps from slide markers.

**Requirements:**
- Extract chapter titles from:
  - Keynote slide titles (via presenter notes import)
  - First sentence after each `[SN]` marker
  - Optional `[chapter:Title]` markers for explicit chapter names
- Calculate timestamps from aligned marker timings
- Output copy-paste ready format:
  ```
  CHAPTERS
  ━━━━━━━━
  0:00 Introduction
  1:23 What is Gnommo?
  3:45 Setting Up Your Project
  7:12 Recording Tips
  10:30 Rendering Your Video
  12:45 Outro
  ```
- Option to merge small chapters (minimum duration threshold)
- Support for nested chapters (main topics + subtopics)

---

## 3. Subtitle/Caption Export

**Command:** `gnommo -p <project> subtitles`

Generate subtitle files from Whisper transcription.

**Requirements:**
- Export formats: SRT, VTT, TXT
- Use existing word-level timestamps from transcription
- Smart line breaking (max characters per line, break at punctuation)
- Speaker diarization support (future: multiple speakers)
- Options:
  - `--format srt|vtt|txt`
  - `--max-chars 42` (characters per line)
  - `--max-duration 5` (seconds per subtitle block)

**Example output (SRT):**
```
1
00:00:01,500 --> 00:00:04,200
Hello and welcome to this tutorial
on video editing with Gnommo.

2
00:00:04,500 --> 00:00:07,800
Today we're going to cover
the complete workflow.
```

---

## 4. Thumbnail Generation

**Command:** `gnommo -p <project> thumbnail`

Auto-generate thumbnail candidates from slides.

**Requirements:**
- Designate thumbnail slides with `[thumbnail]` marker
- If no marker, use slide 1 or title slide
- Apply text overlays from config:
  ```json
  {
    "thumbnail": {
      "title_text": "Episode ${episode_number}",
      "subtitle_text": "${title}",
      "font": "Impact",
      "text_color": "#FFFFFF",
      "outline_color": "#000000",
      "position": "bottom-left"
    }
  }
  ```
- Generate multiple variants:
  - With/without text overlay
  - Different zoom levels
  - Different color treatments (saturated, high contrast)
- Output to `out/thumbnails/` folder
- Resolution: 1280x720 (YouTube standard)

---

## 5. Intro/Outro Templates

**Configuration in project.json:**
```json
{
  "intro": {
    "template": "templates/intro_v2.mp4",
    "duration": 3.5,
    "transition": "fade",
    "variables": {
      "episode_number": "12",
      "title": "Getting Started with Gnommo"
    }
  },
  "outro": {
    "template": "templates/outro_subscribe.mp4",
    "duration": 8.0,
    "transition": "fade"
  }
}
```

**Requirements:**
- Define intro/outro templates in `shared_assets/templates/`
- Auto-prepend intro before first slide
- Auto-append outro after last slide
- Support variable substitution in templates (episode number, title)
- Configurable transition types (fade, cut, wipe)
- End screen safe zone support (last 20 seconds)

---

## 6. Multi-Platform Format Presets

**Command:** `gnommo -p <project> render --format <preset>`

**Presets:**
| Preset | Aspect | Resolution | Notes |
|--------|--------|------------|-------|
| `youtube` | 16:9 | 1920x1080 | Default, standard horizontal |
| `youtube-4k` | 16:9 | 3840x2160 | 4K export |
| `shorts` | 9:16 | 1080x1920 | Vertical, auto-reframe slides |
| `podcast` | - | Audio only | MP3/M4A export for podcast feeds |
| `square` | 1:1 | 1080x1080 | Instagram/LinkedIn |

**Requirements:**
- Auto-adjust cutout positions per format
- Smart slide reframing for vertical (zoom to content area)
- Separate output folders per format
- Batch export to multiple formats: `--format youtube,shorts,podcast`

---

## 7. Teleprompter Script Generation

**Command:** `gnommo -p <project> teleprompter`

Extract clean narration text for teleprompter display.

**Requirements:**
- Strip all markers from manuscript
- Keep only spoken text
- Output formats:
  - `--format txt` - Plain text
  - `--format html` - Scrollable HTML page with large font
  - `--format json` - For teleprompter apps
- Optional: Include slide thumbnails as visual cues
- Configurable font size and scroll speed hints

**Example HTML output:**
```html
<div class="teleprompter">
  <p class="cue">[SLIDE: Introduction]</p>
  <p>Hello and welcome to this tutorial on video editing with Gnommo.</p>
  <p class="cue">[SLIDE: What is Gnommo?]</p>
  <p>Gnommo is a code-first video editing pipeline...</p>
</div>
```

---

## 8. Recording Checklist Generator

**Command:** `gnommo -p <project> checklist`

Generate a pre-recording checklist based on project configuration.

**Output includes:**
- [ ] Camera settings (resolution, fps from project.json)
- [ ] Lighting setup (if green screen detected in videos.json)
- [ ] Audio check (microphone levels)
- [ ] Props/demos needed (parsed from `[video:...]` markers)
- [ ] Slide count and estimated duration
- [ ] Teleprompter ready
- [ ] Recording space clear

**Customizable via `checklist_template.md` in project folder.**

---

## 9. Audio Normalization

**Automatic during render or standalone command:**
`gnommo -p <project> normalize`

**Requirements:**
- Target: -14 LUFS (YouTube standard)
- Apply loudness normalization to narration track
- Preserve dynamic range (avoid over-compression)
- Normalize intro/outro audio to match
- Option: `--target-lufs -14`

**Implementation:**
- Use FFmpeg `loudnorm` filter
- Two-pass normalization for accurate results
- Report before/after levels

---

## 10. Project Templates

**Command:** `gnommo init <project-name> --template <template>`

**Built-in templates:**
| Template | Description |
|----------|-------------|
| `tutorial` | Talking head + slides, square slide layout |
| `explainer` | Full-screen slides, minimal presenter |
| `review` | Product review format, multiple camera angles |
| `talking-head` | Full-screen presenter, no slides |
| `screencast` | Screen recording with small presenter PIP |

**Requirements:**
- Templates stored in `~/.gnommo/templates/` or `shared_assets/templates/`
- Each template includes:
  - `project.json` with preset cutouts and settings
  - `manuscript.txt` skeleton with example markers
  - Sample `videos.json` structure
- User can create custom templates: `gnommo template save <name>`

---

## 11. Batch Processing

**Command:** `gnommo batch render project1 project2 project3`

**Requirements:**
- Process multiple projects in sequence
- Continue on failure (don't stop batch for one failed project)
- Summary report at end:
  ```
  BATCH COMPLETE
  ━━━━━━━━━━━━━━
  ✓ project1 - rendered in 5:23
  ✓ project2 - rendered in 4:17
  ✗ project3 - failed (missing slide S12)
  ```
- Options:
  - `--parallel 2` - Run N renders in parallel
  - `--skip-existing` - Skip if `out/final.mp4` exists
  - `--format youtube,shorts` - Render all formats for each project

---

## 12. Progress Dashboard

**Command:** `gnommo status` or `gnommo -p <project> status`

Display pipeline status for all projects or specific project.

**Output:**
```
PROJECT STATUS
━━━━━━━━━━━━━━
Project     Import  Preprocess  Transcribe  Render   Output
─────────────────────────────────────────────────────────────
video1      ✓       ✓           ✓           ✓        final.mp4 (12:34)
video2      ✓       ✓           ✓           ✗        -
video3      ✓       ✗           -           -        -
video4      ✗       -           -           -        -
```

**Requirements:**
- Scan all project directories
- Check for existence of intermediate files
- Show file timestamps and durations
- Highlight what needs to be done next

---

## 13. Recording Session Mode (Future)

**Command:** `gnommo -p <project> session`

Live recording assistant mode.

**Features:**
- Display current slide on secondary monitor
- Show teleprompter text overlay
- Keyboard shortcuts to advance slides
- Real-time recording with proper settings
- Auto-stop at end of manuscript
- Voice command support: "next slide", "pause"

**Note:** This is a stretch goal requiring significant UI work.

---

## Implementation Priority

### Phase 1 - Core YouTube Workflow (High Impact)
1. **Video Description Generator** (citations + Pexels attribution)
2. **YouTube Chapter Markers**
3. **Subtitle/Caption Export**
4. **Audio Normalization**

### Phase 2 - Content Creation Efficiency
5. **Thumbnail Generation**
6. **Intro/Outro Templates**
7. **Teleprompter Script Generation**
8. **Recording Checklist Generator**

### Phase 3 - Scale & Automation
9. **Project Templates**
10. **Multi-Platform Format Presets**
11. **Batch Processing**
12. **Progress Dashboard**

### Phase 4 - Advanced
13. **Recording Session Mode**

---

## Notes

- All new commands should follow existing CLI pattern: `gnommo -p <project> <command>`
- Output files go to `out/` subdirectory by default
- All features should support `--dry-run` where applicable
- Verbose mode (`-v`) should show detailed progress
