Youtube Player Widget
A YouTube player widget for Foundry VTT. The GM picks what plays and every connected player sees and hears it in sync, so you can use YouTube music and ambience at the table without sending links around. Build playlists, keep a tagged library of your favorite tracks, and let the music change on its own when a scene is activated or combat starts.
Getting Started
The module needs an SSL certificate to work properly: the address you use to connect to Foundry must start with https. This only matters if you host Foundry yourself; you can follow these instructions (opens in a new tab) to set it up.

The widget sits above the Player List at the bottom left of the screen. To play your first video:
- Paste a YouTube link (or a video ID) in the
Video URLfield. - Press
Enteror click Play.
The video now plays for everyone. Links from youtu.be, watch, shorts and live pages all work, and a ?t= timestamp in the link starts the video at that point.
Hover over the video to show its controls:
- Mute and Volume: your own volume. Each player sets their own, and the GM's volume doesn't change anyone else's.
- Seek bar (GM only): jump to another point of the video. Everyone follows.
Players only see the video and the volume controls: everything else is for the GM.
To move the widget, drag the faint bar along its bottom edge (the cursor turns into a move cursor over it). Double-click that bar, or drop the widget in the bottom-left corner of the screen, to put it back in its place above the Player List.
Main Toolbar
The buttons under the video, from left to right (hover over a button to see its name):
- Play: play the link in the
Video URLfield - Stop: stop the video for everyone
- Sound Library: open the Sound Library
- Search YouTube: open the search panel
- Toggle Playlists: show or hide the playlists panel next to the video
Search interface
Search needs your own YouTube API key, set in the module settings. Without one, searching shows a warning. See Using your own YouTube API Key, it's free and takes a few minutes.
- Type in the search field and press
Enteror the search button. - Click a result to play it right away.
- Right-click a result to
Add to Playlist,Copy URLorAdd to Sound Library.
Playlists

Click Toggle Playlists to open the playlist panel. Pick a playlist from the dropdown at the top, or use the buttons next to it to Create, Rename or Delete a playlist.
To add a video, paste its link in the Video URL field and click Add to Playlist (the + at the bottom of the panel). You can also paste the link of a whole YouTube playlist: you are asked for a name to create a new playlist with all its videos, or you can leave the name empty to add them to the current playlist.
- Click a track to play it. The speaker icon shows which track is playing.
- Drag tracks to change their order.
- Click the repeat icon on a track to play it on repeat (Repeat Track).
- Right-click a track to
Edit Track,Copy URL,Add to Sound Library,Delete Track, or use it as a scene or battle soundtrack. - Videos that can't be played (for example removed or private ones, or ones whose owner doesn't allow them outside YouTube) are marked with a warning and skipped. Click one to try it again.
The buttons at the bottom of the panel change how the selected playlist plays:
- Shuffle: play the tracks in random order
- Loop Playlist: start over after the last track
- Toggle Auto-Play: go on to the next track when one ends
- Default Battle Playlist: play this playlist when combat starts (see Scene and Combat Soundtracks)
- Previous Track / Next Track: skip back or forward
When you switch or stop tracks the volume fades out and in. You can change how long the fade lasts, or turn it off, with the Fade Duration (seconds) setting.
Edit Track

Right-click a track and choose Edit Track to change its title or to play only part of the video: set a Start Time and/or an End Time, in seconds (90) or minutes and seconds (1:30). This is handy for long videos where you only want one song or a stretch of ambience.
Sound Library

The Sound Library is one big collection of all your favorite tracks, sorted with your own colored tags (for example Tavern, Combat, Dungeon). Use it to find the right music quickly during a session. Open it with the Sound Library button.
- Click the
⋮button in the window header and chooseTags Configurationto create your tags: give each a name and a color. - In the same menu, choose
Add Tracksand paste video or YouTube playlist links, one per line. ClickImport: the titles are filled in for you and videos already in the library are skipped. You can also right-click a search result or a playlist track and chooseAdd to Sound Library. - Right-click a track and choose
Configure Trackto set its tags, title, start and end time.
Using the library:
- Click a track (or its play button) to play it.
- Type in
Search...to filter by title, and use the dropdown to sort (Title A–Z,Title Z–A,Recently added). - Click a tag under the search field to hide or show the tracks with that tag.
- Right-click a track to
Play,Add to Playlist,Copy URL,Configure Track,Delete Track, or use it as a scene or battle soundtrack. - Tick the boxes next to tracks to change many at once: pick a tag from the dropdown, then add or remove it, add the tracks to the current playlist, select all visible tracks, clear the selection, or delete them.
Scene and Combat Soundtracks

You can link music to a scene so it starts on its own:
- Scene Soundtrack: plays when the scene is activated, unless it is already playing.
- Battle Music: plays when combat starts on the scene. When the combat ends, the music that was playing before comes back where it left off.
Each one can be a whole playlist, a single playlist track, or a track from the Sound Library. Set them in Scene Config -> Miscellaneous tab -> YouTube Soundtrack section, or right-click a track and choose Set as Scene Soundtrack or Set as Scene Battle Music to use it on the scene you are viewing.
For scenes without their own battle music you can set a default battle music: right-click a track and choose Set as Default Battle Music, or select a playlist and turn on its Default Battle Playlist button.
Journal Links
You can put a link that plays a video in a Journal, an item description, a chat message, or any other text that Foundry turns into links. Write @YT, then the video ID in square brackets, then the link text in curly brackets:
@YT[videoId]{Video Title}The video ID is the code after v= in the link (for https://www.youtube.com/watch?v=vyg5jJrZ42s it is vyg5jJrZ42s). Without the curly brackets the link reads YouTube Video. When the GM clicks the link, the video plays in the widget.
Settings
In Game Settings -> Configure Settings -> Youtube Player Widget:
- Import/Export:
Open Import/Export Dialogto save playlists and the Sound Library to a file, or load them from one (see Import and Export). - YouTube API Key: your own key, needed for search. See Using your own YouTube API Key.
- Link to Music Volume: on by default, the widget follows Foundry's own
Musicvolume slider. Turn it off to give the widget its own volume (each user sets this for themselves). - YouTube Volume: your own widget volume when it isn't linked to the Music volume. You can also change it from the widget.
- Show YouTube Controls: show YouTube's own controls on the video (chapters, captions, quality). Off by default; the widget's volume and seek bar are always there.
- Fade Duration (seconds): how long the volume fades when switching or stopping tracks.
0turns the fade off.
Import and Export

Use this to move your music to another world, or to keep a backup.
- Export: tick the playlists you want and click
Export Selected Playlists, or clickExport Sound Libraryto save the whole library with its tags. - Import: choose a file you exported. For a playlists file, tick the playlists to import and click
Import Selected Playlists. For a library file, clickImport Sound Library: tags with the same name are reused and videos already in the library are skipped.
FAQ
Can I hide the video?
Unfortunately, hiding the video is not an option as it contravenes YouTube's terms of service. For this reason, the module does not accommodate this feature.
It's worth noting that attempting to hide the video using CSS would create a confusing user experience where audio is playing but no controls are present, rendering it an inadequate solution.
How do ADs work?
The module utilizes the YouTube API to stream videos, which includes any accompanying advertisements. If the video contains ads, they will be displayed during playback. However, if you are logged into the same browser with a YouTube Premium subscription, ads will be automatically skipped.
It's important to understand that ad handling is user-specific. Therefore, if one user has YouTube Premium while another does not, ads will only be bypassed for the Premium user.
Troubleshooting
"Sign in to confirm you're not a bot" message
Sometimes YouTube shows a protection screen instead of the video, with a message like:
Sign in to confirm you're not a bot. This helps protect our community.
This check is performed entirely by YouTube and usually appears when YouTube suspects automated traffic or wants you to confirm your identity.
To resolve it, try the following steps:
-
Use a normal browser tab
- Open Foundry VTT in a regular (non‑incognito) tab of your browser.
- Avoid using private / incognito windows when you want to play YouTube videos inside Foundry.
-
Make sure you are logged into YouTube in the same browser
- In the same browser where Foundry is open, open a new tab and go to
https://www.youtube.com/. - Log in with your Google account and confirm that you can watch videos normally.
- Go back to the Foundry tab and reload the page, then try playing the video again.
- In the same browser where Foundry is open, open a new tab and go to
-
Disable VPNs, proxies, and aggressive privacy tools
- Turn off any VPN, proxy, or corporate tunneling software while testing.
- Temporarily disable browser extensions that heavily block ads, trackers, or modify network requests (for example, very strict ad‑blockers or privacy add‑ons), then refresh Foundry and try again.
-
Try a different browser/profile
- If the problem persists, try opening Foundry from another browser (or a clean browser profile) where you are logged into YouTube and no VPN/incognito mode is in use.
- This helps confirm whether the issue is tied to a specific browser profile or extension.
-
Wait and try again later
- In some cases YouTube may temporarily flag your IP or session (for example after using a VPN or unusual traffic).
- If none of the steps above help, wait 24 hours and try again; the block often clears on its own.
If the YouTube protection screen still appears after all of the above, it means YouTube is still enforcing the check for that user or connection. The widget cannot bypass this, because the video and all related verification are handled directly by YouTube.
Advanced
Using your own YouTube API Key
The API key is free and allows up to 100 searches per day.
Searching YouTube from the widget needs your own YouTube API key. The key also makes importing YouTube playlists and loading track titles faster: without it, playlist imports go through theripper93's server.
-
Sign in to Google: If you don't have a Google account, you'll need to create one. If you already have one, proceed to sign in to your Google account.
-
Go to Google Cloud Console: Open your web browser and navigate to the Google Cloud Console (opens in a new tab).
-
Create a new project (if necessary): If you don't have any projects listed or if you want to create a new one, click on the project drop-down menu at the top of the page, then select "New Project". Follow the prompts to create a new project and give it a name.
-
Enable the YouTube Data API v3: In the Cloud Console, navigate to the "APIs & Services" > "Library" page using the sidebar menu.
-
Search for YouTube Data API v3: In the search bar, type "YouTube Data API v3" and select it from the search results.
-
Enable the API: On the YouTube Data API v3 page, click the "Enable" button. This will enable the API for use with your project.
-
Create API Key: After enabling the API, go to "APIs & Services" > "Credentials" using the sidebar menu.
-
Create Credentials: Click on the "Create Credentials" drop-down menu and select "API key".
-
Copy your API Key: Once your API key is created, you will see it displayed on the screen. Copy the API key.
-
Set up your API Key in Foundry VTT: In Foundry VTT, go to
Game Settings->Configure Settings->Youtube Player Widgetand paste your API key intoYouTube API Key.
That's it! You can now search YouTube from the widget.
Macros
The module has an API for macros at game.modules.get("fvtt-youtube-player").api. The commands that change the music work for the GM only.
This macro starts the Combat playlist in random order:
const yt = game.modules.get("fvtt-youtube-player").api;
yt.playPlaylist("Combat", { shuffle: true });| Command | What it does |
|---|---|
play(urlOrId) | Play a YouTube link or video ID |
stop() | Stop the video |
pause() / resume() | Pause or resume the current video |
seek(seconds) | Jump to a point of the current video |
next() / previous() | Skip within the playing playlist |
playPlaylist(nameOrId, { shuffle, track }) | Start a playlist by name or ID, optionally from a track (ID, title or position) |
addToPlaylist(url) | Add a video or YouTube playlist to the selected playlist |
getPlaylists() | Get a copy of all playlists |
getState() | Get what is playing: link, video ID, time, paused, playlist and track |
The module also calls two hooks: fvtt-youtube-player.trackStart when a video starts (with its url, videoId and track) and fvtt-youtube-player.stop when it stops.
CSS
The module offers some classes you can use to customize the player if you wish to do so. Note that it's against YouTube's terms of service to hide the video, but you can customize other things such as its border.
Customizing the border for GMs and Players
.fvtt-youtube-player-is-gm-true{
border: 1px solid red;
}
.fvtt-youtube-player-is-gm-false{
border: 1px solid blue;
}