gnommo/tasks.md

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:

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

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

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

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

<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