/rznies/youtube_notes

Wiki directory

Browse AI-generated documentation for any repository.

Home

Relevant source files

The following files were used as context for generating this wiki page:

Nota is a "Random Access Intelligence" engine designed to transform long-form YouTube content into actionable, structured intelligence. Instead of simple summarization, the application provides real-time transcript synchronization and AI-powered analysis, turning lengthy videos into a concise, explorable workspace. The core functionality revolves around fetching a video's transcript, allowing users to generate "Surgical AI Notes" on specific selections, and automatically creating a "Smart Board" of high-level content like key takeaways, social media posts, and blog outlines.

The system is built with a modern web stack, featuring a React/TypeScript frontend that communicates with a Python/FastAPI backend for transcript retrieval and the Google Gemini API for all AI-driven content generation. The application emphasizes a high-quality user experience with a premium dark theme, a focus on performance, and a strong design philosophy that avoids generic aesthetics.

Sources: README.md, App.tsx, api/index.py, extensions/frontend-design/skills/frontend-design/SKILL.md

System Architecture

The application follows a distributed architecture comprising a React single-page application (SPA), a lightweight Python backend acting as a proxy, and external AI services.

Generating architecture diagram...

This diagram shows the overall system flow, from a user pasting a URL to the generation and display of AI content and notes.

Frontend: A React 18 SPA built with Vite and TypeScript. It handles all user interactions, state management, and direct communication with the Google Gemini API. It uses localStorage to persist notes and generated content for each video.
Sources: package.json, hooks/useNotes.ts, hooks/useContentGenerator.ts
Backend: A Python FastAPI server that exposes a single endpoint (/api/transcript) to fetch video transcripts. It acts as a proxy to the youtube-transcript-api library, adding rate limiting and CORS policies.
Sources: api/index.py
AI Service: The Google Gemini API is used for all generative AI tasks. It's called directly from the frontend for generating margin notes and the full suite of Smart Board content.
Sources: services/geminiService.ts, README.md:27

Core User Flow: From URL to Intelligence

The primary workflow begins when a user provides a YouTube URL and culminates in the display of a full suite of AI-generated content.

Generating architecture diagram...

This sequence illustrates the orchestration between frontend components, hooks, the backend API, and the Gemini API to process a video.

Sources: App.tsx:32-49, hooks/useTranscript.ts:37-53, hooks/useContentGenerator.ts:80-136, api/index.py:80-99

Key Features

Smart Board Analysis

The Smart Board is the central dashboard for AI-generated content derived from the entire video transcript. It is managed by the SmartBoard.tsx component and populated by the useContentGenerator hook.

Sources: components/SmartBoard.tsx, hooks/useContentGenerator.ts

Content Generation

When a transcript is successfully loaded, the generateAll function is triggered, which runs four distinct AI generation tasks in parallel using Promise.allSettled. Each task has a specific system instruction sent to the Gemini API to produce a structured output.

Content Type	Generating Function	Gemini System Instruction	Output Format
Key Takeaways	`generateKeyTakeaways`	Extracts 5-7 actionable, concise takeaways.	JSON array of `KeyTakeaway` objects.
Twitter Thread	`generateTwitterThread`	Creates a 7-10 tweet thread with a hook and conclusion.	Numbered list parsed into a string array.
LinkedIn Post	`generateLinkedInPost`	Creates a professional post with a hook, body, CTA, and hashtags.	JSON `LinkedInPost` object.
Blog Outline	`generateBlogOutline`	Creates an SEO-optimized outline with a title, sections, and keywords.	JSON `BlogOutline` object.

Sources: hooks/useContentGenerator.ts:104-110, services/geminiService.ts:63, 140, 156, 172

Caching

All generated content is stored in localStorage with a key prefixed by tldw_content_ followed by the videoId. This prevents re-generation for previously processed videos and allows for instant loading on subsequent visits.

Sources: hooks/useContentGenerator.ts:40-57

Surgical AI Notes

This feature allows users to get a concise summary of any specific part of the transcript.

Flow

The user highlights text in the TranscriptColumn.
The onSelection callback in App.tsx updates the state with the selected text, start time, and screen position.
A FloatingActionButton appears near the selection.
The user clicks the "Analyze" button, which calls handleAnalyze.
handleAnalyze invokes the addNote function from the useNotes hook.
addNote calls cleanTranscriptText in geminiService.ts, which sends the raw text to the Gemini API with a specific prompt to clean it up.
The returned cleanedText is used to create a Note object, which is saved to localStorage and the UI is updated.

Generating architecture diagram...

This diagram shows the process of creating a single AI-powered note from a text selection.

Sources: App.tsx:51-66, hooks/useNotes.ts:27-51, services/geminiService.ts:12-44

Backend API

The backend is a minimal FastAPI application responsible solely for fetching YouTube transcripts.

Sources: api/index.py

Endpoint: `GET /api/transcript`

Property	Description
Path	`/api/transcript`
Method	`GET`
Query Parameter	`videoId` (string, required, min/max length 11)
Success Response (200)	A JSON array of transcript segments: `[{ "text": "...", "start": 0.0, "duration": 1.0 }]`
Error Responses	`404 Not Found`: If transcript is disabled or unavailable. `429 Too Many Requests`: If rate limit is exceeded. `403 Forbidden`: If YouTube is blocking the server IP. `500 Internal Server Error`: For other exceptions.

Sources: api/index.py:80-99, tests/api_test.py

Middleware

The API is protected by several layers of middleware:

Strict CORS: Restricts requests to allowed origins defined in the ALLOWED_ORIGINS environment variable.
Sources: api/index.py:48-54
Rate Limiting: A custom middleware that limits clients to 15 requests per 60 seconds by tracking their IP address.
Sources: api/index.py:12-14, 27-39
Security Headers: Adds X-Content-Type-Options, X-Frame-Options, and Strict-Transport-Security headers to all responses.
Sources: api/index.py:19-24

Data Models

The application's data structures are defined in types.ts.

Sources: types.ts

Generating architecture diagram...

This diagram illustrates the composition of the main ContentOutput type, which aggregates all AI-generated content for the Smart Board. Note and TranscriptSegment are independent top-level types.

Key Interfaces

Interface	Field	Type	Description
Note	`id`	`string`	Unique identifier for the note.
	`videoId`	`string`	The YouTube video this note belongs to.
	`originalText`	`string`	The raw text highlighted by the user.
	`cleanedText`	`string`	The AI-summarized version of the text.
	`timestamp`	`number`	The start time (in seconds) of the selection.
	`createdAt`	`number`	Unix timestamp of when the note was created.
TranscriptSegment	`id`	`string`	Unique identifier for the segment.
	`startTime`	`number`	Start time of the segment in seconds.
	`text`	`string`	The text content of the segment.
	`duration`	`number`	Duration of the segment in seconds.

Sources: types.ts:1-20

Frontend Design & Styling

The project's visual identity is a key consideration, with a philosophy of creating "distinctive, production-grade frontend interfaces" that avoid generic AI aesthetics.

Sources: extensions/frontend-design/skills/frontend-design/SKILL.md:1-4

Theme and Colors

The application uses Tailwind CSS with a custom theme configured directly in index.html. It establishes a premium dark theme with a specific color palette.

Name	Value	Description
`background`	`#09090b`	Main app background color.
`surface`	`#18181b`	Surface color for panels like the Smart Board.
`yt-black`	`#0f0f0f`	A deep black, used in the header.
`yt-gray`	`#272727`	Gray for secondary elements like note cards.
`yt-red`	`#ff0000`	YouTube's brand red for accents.
`primary`	`#3b82f6`	Primary blue for interactive elements.

Sources: index.html:9-23

Design Philosophy

The guiding principles for design emphasize:

Typography: Using distinctive, characterful fonts instead of generic choices.
Color & Theme: Committing to a cohesive aesthetic with dominant colors and sharp accents.
Motion: Using animations for high-impact moments and micro-interactions.
Spatial Composition: Employing unexpected layouts, asymmetry, and controlled use of space.
Visual Details: Adding textures, gradients, and other details to create atmosphere.

Sources: extensions/frontend-design/skills/frontend-design/SKILL.md:22-35

Home

Relevant source files

The following files were used as context for generating this wiki page:

Sources: README.md, App.tsx, api/index.py, extensions/frontend-design/skills/frontend-design/SKILL.md

System Architecture

The application follows a distributed architecture comprising a React single-page application (SPA), a lightweight Python backend acting as a proxy, and external AI services.

Generating architecture diagram...

This diagram shows the overall system flow, from a user pasting a URL to the generation and display of AI content and notes.

Frontend: A React 18 SPA built with Vite and TypeScript. It handles all user interactions, state management, and direct communication with the Google Gemini API. It uses localStorage to persist notes and generated content for each video.
Sources: package.json, hooks/useNotes.ts, hooks/useContentGenerator.ts
Backend: A Python FastAPI server that exposes a single endpoint (/api/transcript) to fetch video transcripts. It acts as a proxy to the youtube-transcript-api library, adding rate limiting and CORS policies.
Sources: api/index.py
AI Service: The Google Gemini API is used for all generative AI tasks. It's called directly from the frontend for generating margin notes and the full suite of Smart Board content.
Sources: services/geminiService.ts, README.md:27

Core User Flow: From URL to Intelligence

The primary workflow begins when a user provides a YouTube URL and culminates in the display of a full suite of AI-generated content.

Generating architecture diagram...

This sequence illustrates the orchestration between frontend components, hooks, the backend API, and the Gemini API to process a video.

Sources: App.tsx:32-49, hooks/useTranscript.ts:37-53, hooks/useContentGenerator.ts:80-136, api/index.py:80-99

Key Features

Smart Board Analysis

Sources: components/SmartBoard.tsx, hooks/useContentGenerator.ts

Content Generation

Content Type	Generating Function	Gemini System Instruction	Output Format
Key Takeaways	`generateKeyTakeaways`	Extracts 5-7 actionable, concise takeaways.	JSON array of `KeyTakeaway` objects.
Twitter Thread	`generateTwitterThread`	Creates a 7-10 tweet thread with a hook and conclusion.	Numbered list parsed into a string array.
LinkedIn Post	`generateLinkedInPost`	Creates a professional post with a hook, body, CTA, and hashtags.	JSON `LinkedInPost` object.
Blog Outline	`generateBlogOutline`	Creates an SEO-optimized outline with a title, sections, and keywords.	JSON `BlogOutline` object.

Sources: hooks/useContentGenerator.ts:104-110, services/geminiService.ts:63, 140, 156, 172

Caching

Sources: hooks/useContentGenerator.ts:40-57

Surgical AI Notes

This feature allows users to get a concise summary of any specific part of the transcript.

Flow

The user highlights text in the TranscriptColumn.
The onSelection callback in App.tsx updates the state with the selected text, start time, and screen position.
A FloatingActionButton appears near the selection.
The user clicks the "Analyze" button, which calls handleAnalyze.
handleAnalyze invokes the addNote function from the useNotes hook.
addNote calls cleanTranscriptText in geminiService.ts, which sends the raw text to the Gemini API with a specific prompt to clean it up.
The returned cleanedText is used to create a Note object, which is saved to localStorage and the UI is updated.

Generating architecture diagram...

This diagram shows the process of creating a single AI-powered note from a text selection.

Sources: App.tsx:51-66, hooks/useNotes.ts:27-51, services/geminiService.ts:12-44

Backend API

The backend is a minimal FastAPI application responsible solely for fetching YouTube transcripts.

Sources: api/index.py

Endpoint: `GET /api/transcript`

Property	Description
Path	`/api/transcript`
Method	`GET`
Query Parameter	`videoId` (string, required, min/max length 11)
Success Response (200)	A JSON array of transcript segments: `[{ "text": "...", "start": 0.0, "duration": 1.0 }]`
Error Responses	`404 Not Found`: If transcript is disabled or unavailable. `429 Too Many Requests`: If rate limit is exceeded. `403 Forbidden`: If YouTube is blocking the server IP. `500 Internal Server Error`: For other exceptions.

Sources: api/index.py:80-99, tests/api_test.py

Middleware

The API is protected by several layers of middleware:

Strict CORS: Restricts requests to allowed origins defined in the ALLOWED_ORIGINS environment variable.
Sources: api/index.py:48-54
Rate Limiting: A custom middleware that limits clients to 15 requests per 60 seconds by tracking their IP address.
Sources: api/index.py:12-14, 27-39
Security Headers: Adds X-Content-Type-Options, X-Frame-Options, and Strict-Transport-Security headers to all responses.
Sources: api/index.py:19-24

Data Models

The application's data structures are defined in types.ts.

Sources: types.ts

Generating architecture diagram...

Key Interfaces

Interface	Field	Type	Description
Note	`id`	`string`	Unique identifier for the note.
	`videoId`	`string`	The YouTube video this note belongs to.
	`originalText`	`string`	The raw text highlighted by the user.
	`cleanedText`	`string`	The AI-summarized version of the text.
	`timestamp`	`number`	The start time (in seconds) of the selection.
	`createdAt`	`number`	Unix timestamp of when the note was created.
TranscriptSegment	`id`	`string`	Unique identifier for the segment.
	`startTime`	`number`	Start time of the segment in seconds.
	`text`	`string`	The text content of the segment.
	`duration`	`number`	Duration of the segment in seconds.

Sources: types.ts:1-20

Frontend Design & Styling

The project's visual identity is a key consideration, with a philosophy of creating "distinctive, production-grade frontend interfaces" that avoid generic AI aesthetics.

Sources: extensions/frontend-design/skills/frontend-design/SKILL.md:1-4

Theme and Colors

The application uses Tailwind CSS with a custom theme configured directly in index.html. It establishes a premium dark theme with a specific color palette.

Name	Value	Description
`background`	`#09090b`	Main app background color.
`surface`	`#18181b`	Surface color for panels like the Smart Board.
`yt-black`	`#0f0f0f`	A deep black, used in the header.
`yt-gray`	`#272727`	Gray for secondary elements like note cards.
`yt-red`	`#ff0000`	YouTube's brand red for accents.
`primary`	`#3b82f6`	Primary blue for interactive elements.

Sources: index.html:9-23

Design Philosophy

The guiding principles for design emphasize:

Typography: Using distinctive, characterful fonts instead of generic choices.
Color & Theme: Committing to a cohesive aesthetic with dominant colors and sharp accents.
Motion: Using animations for high-impact moments and micro-interactions.
Spatial Composition: Employing unexpected layouts, asymmetry, and controlled use of space.
Visual Details: Adding textures, gradients, and other details to create atmosphere.

Sources: extensions/frontend-design/skills/frontend-design/SKILL.md:22-35

Home

System Architecture

Core User Flow: From URL to Intelligence

Key Features

Smart Board Analysis

Content Generation

Caching

Surgical AI Notes

Flow

Backend API

Endpoint: GET /api/transcript

Middleware

Data Models

Key Interfaces

Frontend Design & Styling

Theme and Colors

Design Philosophy

Home

System Architecture

Core User Flow: From URL to Intelligence

Key Features

Smart Board Analysis

Content Generation

Caching

Surgical AI Notes

Flow

Backend API

Endpoint: GET /api/transcript

Middleware

Data Models

Key Interfaces

Frontend Design & Styling

Theme and Colors

Design Philosophy

Endpoint: `GET /api/transcript`

Endpoint: `GET /api/transcript`