Youtube Overlay

# YouTube Overlay

**Watch YouTube videos in a floating window on top of Minecraft, while you play.**

YouTube Overlay puts a small video player over your game. Paste a link or type a search, and the video plays with sound in a corner of your screen. It stays visible in-game, in menus and in the pause screen. Move it, resize it, make it see-through, and keep mining.

It's a **client-side mod**. It works in singleplayer and on any server, and the server doesn't need it installed.

## Features
- **Play by link or search:** `/yt play <url>`, or `/yt play lofi hip hop` to play the top search result
- **Floating window:** drag it anywhere, resize it from the corner, and it keeps the video's shape
- **Always on top:** visible in-game and over menus
- **Sound included:** its own volume setting, scaled by Minecraft's master volume
- **Adjustable opacity**, so you can still see the game behind the video
- **Pause, resume and seek** to any point in the video
- **Remembers your settings** (position, size, opacity, volume) between sessions
- **Smooth playback on long videos:** streams are downloaded in chunks to get around YouTube's throttling

## Versions
| Minecraft | Loader |
|---|---|
| 26.3 | Fabric (needs Fabric API) or Forge |
| 1.8.9 | Forge |

---

## Setup

The mod uses two free tools to play videos: **yt-dlp** finds the video stream, and **ffmpeg** decodes it. Install both before using the mod.

### 1. Install yt-dlp and ffmpeg

**Windows** (Command Prompt or PowerShell):
```
winget install yt-dlp.yt-dlp
winget install Gyan.FFmpeg
```

**macOS** ([Homebrew](https://brew.sh)):
```
brew install yt-dlp ffmpeg
```

**Linux:**
```
pipx install yt-dlp
sudo apt install ffmpeg        # or your distro's package manager
```

> ⚠️ **Keep yt-dlp up to date.** YouTube changes often, and old versions of yt-dlp stop working. The copy in your Linux distro's package manager is usually too old. If videos stop loading, update yt-dlp first (`yt-dlp -U`, `pipx upgrade yt-dlp` or `winget upgrade yt-dlp.yt-dlp`).

To check that both work, open a new terminal and run:
```
yt-dlp --version
ffmpeg -version
```
Both should print a version number. **Restart your Minecraft launcher** after installing, so it can find the new tools.

### 2. Install the mod
1. Install your mod loader: **Fabric** with **Fabric API**, or **Forge**, for your Minecraft version.
2. Put the YouTube Overlay `.jar` for your loader and version into your `.minecraft/mods` folder.
3. Start the game.

---

## Usage

### Commands
| Command | What it does |
|---|---|
| `/yt play <url or search>` | Play a video from a YouTube link, or the top result for a search |
| `/yt pause` / `/yt resume` | Pause or continue |
| `/yt stop` | Stop and close the video |
| `/yt seek <time>` | Jump to a time: seconds (`90`) or minutes:seconds (`1:30`) |
| `/yt volume <0-100>` | Set the video volume |
| `/yt opacity <0-100>` | Set how see-through the video is |
| `/yt size <5-100>` | Set the width, as a percentage of the screen |
| `/yt pos <x> <y>` | Move the window: x and y are percentages of the screen |
| `/yt edit` | Open the editor screen |
| `/yt reload` | Reload the config file |
| `/yt help` | Show the command list in chat |

### Editor screen
Press **O** (rebindable in Controls) or run `/yt edit` to open the editor:
- **Drag the video** to move it
- **Drag the bottom-right corner** to resize it
- **Scroll the mouse wheel** to change the volume
- Buttons for **Pause/Resume**, **Stop** and **Opacity −/+**

The editor also shows the video's title, current time, length and volume. Your layout is saved when you close it.

### Configuration
Settings are saved automatically. You can also edit the config file directly and run `/yt reload`:
- **26.3:** `config/ytoverlay.properties`
- **1.8.9:** `config/ytoverlay.cfg`

| Setting | Default | Meaning |
|---|---|---|
| `x`, `y` | `0.6`, `0.03` | Window position, as a fraction of the screen (top-right by default) |
| `width` | `0.37` | Window width, as a fraction of the screen |
| `opacity` | `100` | 0 (invisible) to 100 (solid) |
| `volume` | `60` | 0 to 100 |
| `maxHeight` | `480` | Maximum video quality, in pixels. Lower it (e.g. `360`) if playback stutters |
| `ytdlpPath` | `yt-dlp` | Path to yt-dlp, if it isn't on your PATH |
| `ffmpegPath` | `ffmpeg` | Path to ffmpeg, if it isn't on your PATH |

---

## Troubleshooting
- **"Could not run 'yt-dlp'" or "Could not run 'ffmpeg'":** the tool isn't installed, or Minecraft can't find it. Restart your launcher after installing. If that doesn't help, set `ytdlpPath` / `ffmpegPath` to the tool's full path (for example `C:\\Tools\\yt-dlp.exe` on Windows; note the doubled backslashes in the 26.3 `.properties` file).
- **"yt-dlp failed: ..." or the video never starts:** update yt-dlp. This fixes nearly every loading problem.
- **Choppy or stuttering video:** set `maxHeight` to `360` or `240`. Your CPU decodes the video while Minecraft is running, so lower quality helps on slower machines.
- **No sound:** check `/yt volume` and Minecraft's Master Volume slider. The video sound follows both.

## Notes
- The video plays inside Minecraft only. Other players on a server can't see or hear it.
- Age-restricted, members-only and private videos usually can't be played.
- This mod isn't affiliated with or endorsed by YouTube or Google. Please respect creators and YouTube's Terms of Service.