108 lines
3.9 KiB
Markdown
108 lines
3.9 KiB
Markdown
# 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](https://github.com/yt-dlp/yt-dlp)** - Command-line tool with extensive format/quality options
|
|
- **[Media Downloader](https://github.com/mhogomchungu/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:
|
|
|
|
```bash
|
|
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)**
|
|
|
|
```markdown
|
|
---
|
|
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**
|
|
|
|
```markdown
|
|
<!-- 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](https://vitepress.dev) for web UI
|
|
- WebSocket for real-time communication between browser and server
|
|
- `gray-matter` for parsing YAML frontmatter
|
|
- [`sharp`](https://github.com/lovell/sharp) for image processing (screenshot manipulation)
|