yt2press

A tool to convert YouTube videos into VitePress web app with timestamped screenshots.

How to Use

Step 1: Prepare Your Video

Download or place a video file in the /docs/public directory. Several options are available for downloading YouTube videos:

YouTube Downloader Options

• yt-dlp - Command-line tool with extensive format/quality options
• Media Downloader - Desktop application with modern UI

Choose any method to download your video and save it to /docs/public directory.

Step 2: Start the Development Server

Run the following command in the project directory:

pnpm run dev

This starts the VitePress development server and WebSocket server for communication.

Step 3: Use the Web Interface to Process the Video

1. Open the VitePress website in your browser
2. Enter your video filename in the textbox (e.g. my video [abc123].mp4, presentation.webm, my-video [xyz].mpeg)
3. Press Enter or click Submit

The app will:

• Load the markdown matching the submitted video filename.
  • If it exists: process the video — extract screenshots for timestamps, insert images, and save the markdown.
  • If it does not exist: create the markdown and exit. Edit the new file (add frontmatter or timestamps), then run the web interface again to process the file.

Create/Edit the Markdown File

You may let the web interface create the markdown file automatically, or create it yourself by placing a file in the /docs directory. The filename should match the video filename with any bracketed ID removed and spaces replaced with underscores, for example:

• Video file: my video [abc123].mp4 → Markdown file: my_video.md
• Video file: presentation.webm → Markdown file: presentation.md

If the file is newly created by the web interface, you will need to edit the markdown to provide the content or timestamps the app will use. After editing, use the web interface again to process the file and regenerate screenshots.

The markdown file content can be one of the following:

Option A: YAML Frontmatter (for auto-generating timestamps)

---
interval: 5
dedup: true
---

<!-- Markdown content here can be left empty -->

• interval: Interval in seconds to auto-generate timestamps
• dedup: (Optional) Set to true to remove similar screenshots (defaults to 0.005), or specify a custom threshold value

Option B: Manual Timestamps

<!-- Frontmatter is optional -->
<!-- Content with timestamps... -->

1:30
Mi habitasse hendrerit id tincidunt finibus eleifend dolor aliquet erat egestas.

2:45
Semper pretium donec laoreet convallis accumsan habitasse.

5:00
Velit euismod blandit proin arcu magna.

Timestamps should be in M:SS or MM:SS format on their own line. They will be converted to timestamped screenshot references.

Project Structure

docs/                          # VitePress documentation root
  .vitepress/
    theme/
      components/
        Downloader.vue        # Vue component for entering a video filename (web interface / video input UI)
        Video.vue             # Vue component to display videos and linked timestamps
  public/                      # Directory to put downloaded videos
    images/
      [video-filename]/        # Screenshot folders (auto-generated)
        *.webp                 # Timestamped screenshots
    [video-filename].webm     # Downloaded videos
  [video-filename].md         # Markdown files with content
server.js                       # WebSocket server for handling downloads
group-similar.js               # Script for deduplicating similar screenshots

Dependencies

• Node.js and pnpm
• VitePress for web UI
• WebSocket for real-time communication between browser and server
• gray-matter for parsing YAML frontmatter
• sharp for image processing (screenshot manipulation)