Adding changes version 1

2026-02-06 17:56:05 +01:00
parent 93fa820275
commit fdd275ac0e
30 changed files with 7068 additions and 888 deletions
@@ -0,0 +1,476 @@
+# 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