Feature: Libre Audio

From 5etools Community Wiki
Jump to: navigation, search

PLEASE NOTE: Roll20 Enhancement Suite (aka VTT es/ R20es), is not part of BetteR20 or 5eTools. However; as BetteR20 installation is enhanced/simplified by already having VTT es/R20es installed, this Wiki covers its content to (HOPEFULLY) prevent BetteR20 users from requesting help on BetteR20 issues on the VTTes/R20es Discord server or other platforms (Reddit/Roll20.net Forum, etc).


R20esLOGO.png
VTTes/R20es v1.15.26

LibreAudio.png
BothDMnPC.png

Libre Audio

This feature requires both the GM and Players both use the VTT ES (R20 ES) Extension for this to work properly.

Libre Audio is a feature that allows the GM to add music from external sources from a URL rather than use your Roll20 Disk Quota.


Feature/Formatting Requirements

Supported Media formats Natively Roll20 uses Ogg; (This is Roll20's corporate solution's format which they covert to on site after upload). but with this MP4, MP3, and yes Webm works as well. (Check this list for more information)
The URL must be a direct link (see Suggested Use Guidance on where to host and how to test) 


Information about Direct Links

Direct Link Files

Several features will require the use of direct link files, so what are they?


A directly linked file is one that your browser can stream without use of any site-specific media player (youTube/Spotify both use embedded players), and without additional prior or pass-through authentication or redirection.


... and for the purposes of Roll20, it must also be a file yourself and your players/GM can access.


YouTUBE, SoundCloud & Spotify

Right off the bat, let's answer the most common question - YouTube, Soundcloud & Spotify, don't work. The links they provide do not link the browser to the file, but to a player.
Both sites have embedded code to render parts that file you're listening to/playing thru their site's dedicated server-side player - and since that is how they operate, and that would conflict with Roll20's site working in their website native players - canvas; requests to load youtube/Spotify will fail.
Each website does what it does, and like radio, it only plays one channel (website) at a time. There are ways around that we'll discuss, but from a high-level overview - YouTube and Spotify won't work, and likely never will (natively).


How do you know if a link is a direct file?

By visual inspection:
A pretty easy way to check on that is if the URL (the address in the Address bar) ends with a file extension.
Example ( http://www.domain.com/directory/filename.<extension> [where <extension> could be .mp3, .mp4, .webm, .webp, .png, .gif, , .json etc etc, depending upon what feature you are using (LibreAudio, Animated Background, External Art, Insert Token by URL, Paste image from URL etc
  • For Music that would be files that end with:
.mp3 .mp4 .ogg .flac .wav .webm
  • For Video that would be files that end with:
.webm .avi .mp4


URLs that do not end with the file specifically listed, or that have additional elements on the end often are issuing redirections and so likely will not work.


Example of Bad URLS

examples of bad Media URLs (they won't work, and why they won't work -- so you can avoid them in your testing)


GENERAL

127.0.0.1/Users/GM/My_Documents/Roll20_Animated_Backgrounds/Supercool.mp4
That is a local file (that address is a coded loopback to whatever machine you are on) and nobody else will be able to see it as that URL goes only to that local machine.


https://drive.google.com/drive/u/3/folders/1l-7JbIsb60osH0f06iNzHVnq-0oY-VNp
That link doesn't have the file name, and ... That link either requires authentication, or issues a redirect - if pass-through authentication is required the Roll20 client will not pass that, and redirections are most often changes in HTML. The Roll20 canvas application player doesn't know what to do with it.


https://www.patreon.com/file?h=17052388&i=1882731
Note that the URL ends with ?<something>, that is what is called a GET. It is a means to passover information to the server, while sometimes these occur after the direct file name (ie. https://www.domain.com/directory/file_name.ext?resx=500&resy=270 to return a specific resolution) they are also used to pass authentication to allow login/password or pass thru session authorization.


IMAGES
The simplest and easiest to test.
Enter the URL into a browser you are not logged into any account upon and see what shows up. If the image shows up; check to make sure the image URL hasn't changed as a form of a redirect. IF the images does not show; or the image's URL changes the original URL isn't going to work.



VIDEOS
https://www.youtube.com/watch?v=aRaynveO0MQ
That's a youtube URL - like above, there is a website side action that the link asks the browser to take to redirect or initiate some other elements, and the Roll20 client will not be able to act on that so those links WILL fail. 


AUDIO
https://soundcloud.com/user-585971590/sets/d-d-night
That's a SoundCloud URL, and they don't provide direct file access without API. So the links you get will generate a website side actions that the link will pull alot of HTML/CSS and some server-side scripts - all of which, are not an audio file, and so Roll20's canvas will not fail upon being asked to process.


https://open.spotify.com/track/2xGDOy0pPf7XQSBhvJ9lzn
That's a spotify URL, and they don't provide direct file access, and like Spotify and several audio streaming services links you get will link to their website, the link will pull a lot of HTML/CSS and some server-side scripts - all of which, are not an audio file, and so Roll20's canvas will fail upon being asked to process ANOTHER website inside its own website.


JSON/Homebrew
https://github.com/TheGiddyLimit/homebrew/blob/master/feat/Sample%20-%20Giddy%3B%20Magically%20Gifted%2C%20Whip%20Aficionado.json
While that absolutely does end with the .json extension, you'll note that visiting the site brings up something like this.
Github labeled.png
You'll note that visiting the site shows some hints on what that will not work.
The site has a number of UI elements, navigation bar, tabbed interface, search field, access to account information and some metadata content - all of that meets the concern about embedded media player - in this case a text editor ( ).
HOWEVER -- there is a means to get direct file access. The GitHub RAW button.png (raw) will lead to a direct file link.
https://raw.githubusercontent.com/TheGiddyLimit/homebrew/master/feat/Sample%20-%20Giddy%3B%20Magically%20Gifted%2C%20Whip%20Aficionado.json
This is a feature that is site-specific, but you will find that general concept from time to time - that a file link, instead of going to direct file, will bring up an embedded player, and that the player provides an option for a link to the direct file, or to download the file for use from a hosting service of your choice.
  • https://media.giphy.com/media/bcKmIWkUMCjVm/giphy.gif​​​​
    That's an animated .gif (see the ending bit of text? that says .gif -- the player doesn't use and cannot play animated gifs, if your file doesn't work, and ends in .gif, that's why.
     
  • https://i.imgur.com/zvATqgs.gifv
    That's the new animated .gif format .gifv.  (and in case you're wondering, renaming a file to .webm or mp4 won't make the file's "type" change - the file is written in a specific language/structure.  The player reads that language, and if its not in that language - it just doesn't work. 


By testing
This is the most obvious, but least used. Take the URL and try opening that URL in a different browser, you may also wish to have one of more players confirm that they can do can.}}


IMAGES
VIDEOS
Videos opened in the browser will open the video with a minimal set of controls. (See video below)
BrowserVideoVID.gif


It should not have a lot of ads, playlist, navigation or account management nav bar, or voting/rating system.
ie, not this.
YouTube labeled.png
AUDIO
Direct File URLS for audio will initiate either a file download or prompt the browser to start playing the file. (See sample screenshoot from a Chrome browser below).
AudioPage.png
JSON/Homebrew
When viewed through the browser it will looking like code listing in the browser.
(Example from a RAW address on GitHub.
GithubRAW.png


One/Some/All of my players cannot see/hear the animation/audio, but I can!

Troubleshooting
Check to see if the player(s) are using the supported environment, have the most current versions of the browser and extensions are installed, and configured correctly.
Most likely the URL you have chosen isn't a public address, and so your browser is playing it because YOU/your machine is authorized already to see that file, while your players are not.
Solution Steps:
Move the file to a place everyone has access to (see the specific feature for suggested locations) or by giving everyone access rights to that location.


Features that use this:

LibreAudio
Animated Background
External Art
Insert Token by URL
Paste image from URL
Import by Category; Module Importer/Exporter; Temporary Import

Instruction Walkthrough (How to use it)

Go to the Jukebox and choose to add Jukebox add.png, then choose to Add Track by URL.
The prompt will pop-up for entering the URL, enter the direct URL for the audio track.
(Yup it's just that easy)


There is a shortcut "Alt-#" (turns track/playlist on) and "Alt-S" (stops all tracks that are playing)


This is a popular feature, please see the FAQ below for more specific information
on how to host files, resources and community playlists etc.



Feature Support


Known Issues/Limitations


UPLOADED TRACKS WILL NOT PLAY
When playing a track that was uploaded, while VTTes is enabled, the track does not play.
Work Around:
Look into R20es Settings. Under the Libre Section, and disable the Libre Audio feature. This issue has been reported and reproduced and the developer notified.


 : The URL must be a direct link (see Suggested Use Guidance on where to host and how to test) 


FAQ

MP3 Direct Link Hosting

(By TipMcVenus)
A list of tutorials on how to upload & get a direct mp3 link on some websites.


JukeHost

  1. Create an account & Login
  2. Then go on the Upload page.
  3. Select your sound file (mp3, ogg, ...) you want to upload, name it and click "`Upload`" (note that you can upload multiple files at once, but the total size should not exceed 500 MB)
    Jukehost 1.png
  4. Wait until the end of the upload then you should be redirected on the Library page.
  5. Click on the "`Copy`" button next to the music you just uploaded
    Jukehost 2.png
  6. The direct link should now be copied to your clipboard, paste it anywhere you want



NB: There is no limitation on the storage space, only on the file size (max 100 MB). This service is rather new so expect inaccurate screenshots. If you have any problem/question about this service, feel free to join their Discord server  (https://discord.gg/ZUR6Djs)

Kiwi6

  1. Create an account & Login  
  2. Then go on this page: [1] 
  3. Choose your mp3 file, check that the privacy is set to "`Public`" or "`Unlisted`" then click "`Upload`"
    Kiwi6 1.png 
  4. After the page refreshed (upload is finished) go here: [Library Page]  
  5. Click on the file you just uploaded 
  6. Copy the "`Direct Hotlink`" 
    Kiwi6 2.png


NB: Kiwi6 has some limits but you shouldn't be annoyed by these as they are really high (see [2](https://kiwi6.com/upgrade "Upgrade Page")).

OpenDrive

  1. Create an account  & Login
  2. Go to https://www.opendrive.com/files/
  3. You can choose a folder (eg. Music) or create a new one
  4. Drag and Drop your sound file (mp3, ogg, ...) on the page
  5. Wait until the end of the upload, then right click it
  6. Choose "Links
    OpenDrive 1.png
  7. Then copy the "Direct Link (streaming)"
    OpenDrive 2.png

NB: OpenDrive gives you 5GB of storage but you can [get free space here](https://www.opendrive.com/free "Get Free Space")

DropBox

  1. Upload the file to dropbox
  2. Create a link
  3. The link will end in dl=0, change the dl=0 to dl=1
  4. Paste that modified URL into the Media URL field.

Googledrive

  1. Install this extension on chrome.

'A REQUEST' where possible, please break the playlist into thematic segments.

What formats can be used?

Roll20 uses Ogg; so that works. MP4, MP3, and yes Webm as well.
Check this list for more information


How do I know if I can use a file?

To see if a file is usable:
  1. Try entering the URL and test it.
    1. Try using VLC - Open Network Stream
    2. Inside Network Protocol; In the Please enter a network URL: insert the URL you wish to use.
    3. Choose Play.
  2. Have ANOTHER person not on your network, most likely a player, confirm that they can hear the track.

Why can't my player's hear the Track(s)?

Are your player's using the current version of R20ES?
If no, the must have it to hear the tracks.
Are they able to get to the Track via their browser OUTSIDE of Roll20?
If no, then you need to have a URL they can access, try another hosting service or decrease security on the file.

Can I use Google's drive?

Yes, provided you are using this extension

Playlists for Roll20 games.

Dalenacio.json

[https://github.com/DMsGuild201/Roll20_resources/blob/master/playlist/TipMcVenus.json)

playlists(1).json

[TipMcVenus.json]

playlists(2).json

playlists.json

Best Practices

Information about Direct Links

Direct Link Files

Several features will require the use of direct link files, so what are they?


A directly linked file is one that your browser can stream without use of any site-specific media player (youTube/Spotify both use embedded players), and without additional prior or pass-through authentication or redirection.


... and for the purposes of Roll20, it must also be a file yourself and your players/GM can access.


YouTUBE, SoundCloud & Spotify

Right off the bat, let's answer the most common question - YouTube, Soundcloud & Spotify, don't work. The links they provide do not link the browser to the file, but to a player.
Both sites have embedded code to render parts that file you're listening to/playing thru their site's dedicated server-side player - and since that is how they operate, and that would conflict with Roll20's site working in their website native players - canvas; requests to load youtube/Spotify will fail.
Each website does what it does, and like radio, it only plays one channel (website) at a time. There are ways around that we'll discuss, but from a high-level overview - YouTube and Spotify won't work, and likely never will (natively).


How do you know if a link is a direct file?

By visual inspection:
A pretty easy way to check on that is if the URL (the address in the Address bar) ends with a file extension.
Example ( http://www.domain.com/directory/filename.<extension> [where <extension> could be .mp3, .mp4, .webm, .webp, .png, .gif, , .json etc etc, depending upon what feature you are using (LibreAudio, Animated Background, External Art, Insert Token by URL, Paste image from URL etc
  • For Music that would be files that end with:
.mp3 .mp4 .ogg .flac .wav .webm
  • For Video that would be files that end with:
.webm .avi .mp4


URLs that do not end with the file specifically listed, or that have additional elements on the end often are issuing redirections and so likely will not work.


Example of Bad URLS

examples of bad Media URLs (they won't work, and why they won't work -- so you can avoid them in your testing)


GENERAL

127.0.0.1/Users/GM/My_Documents/Roll20_Animated_Backgrounds/Supercool.mp4
That is a local file (that address is a coded loopback to whatever machine you are on) and nobody else will be able to see it as that URL goes only to that local machine.


https://drive.google.com/drive/u/3/folders/1l-7JbIsb60osH0f06iNzHVnq-0oY-VNp
That link doesn't have the file name, and ... That link either requires authentication, or issues a redirect - if pass-through authentication is required the Roll20 client will not pass that, and redirections are most often changes in HTML. The Roll20 canvas application player doesn't know what to do with it.


https://www.patreon.com/file?h=17052388&i=1882731
Note that the URL ends with ?<something>, that is what is called a GET. It is a means to passover information to the server, while sometimes these occur after the direct file name (ie. https://www.domain.com/directory/file_name.ext?resx=500&resy=270 to return a specific resolution) they are also used to pass authentication to allow login/password or pass thru session authorization.


IMAGES
The simplest and easiest to test.
Enter the URL into a browser you are not logged into any account upon and see what shows up. If the image shows up; check to make sure the image URL hasn't changed as a form of a redirect. IF the images does not show; or the image's URL changes the original URL isn't going to work.



VIDEOS
https://www.youtube.com/watch?v=aRaynveO0MQ
That's a youtube URL - like above, there is a website side action that the link asks the browser to take to redirect or initiate some other elements, and the Roll20 client will not be able to act on that so those links WILL fail. 


AUDIO
https://soundcloud.com/user-585971590/sets/d-d-night
That's a SoundCloud URL, and they don't provide direct file access without API. So the links you get will generate a website side actions that the link will pull alot of HTML/CSS and some server-side scripts - all of which, are not an audio file, and so Roll20's canvas will not fail upon being asked to process.


https://open.spotify.com/track/2xGDOy0pPf7XQSBhvJ9lzn
That's a spotify URL, and they don't provide direct file access, and like Spotify and several audio streaming services links you get will link to their website, the link will pull a lot of HTML/CSS and some server-side scripts - all of which, are not an audio file, and so Roll20's canvas will fail upon being asked to process ANOTHER website inside its own website.


JSON/Homebrew
https://github.com/TheGiddyLimit/homebrew/blob/master/feat/Sample%20-%20Giddy%3B%20Magically%20Gifted%2C%20Whip%20Aficionado.json
While that absolutely does end with the .json extension, you'll note that visiting the site brings up something like this.
Github labeled.png
You'll note that visiting the site shows some hints on what that will not work.
The site has a number of UI elements, navigation bar, tabbed interface, search field, access to account information and some metadata content - all of that meets the concern about embedded media player - in this case a text editor ( ).
HOWEVER -- there is a means to get direct file access. The GitHub RAW button.png (raw) will lead to a direct file link.
https://raw.githubusercontent.com/TheGiddyLimit/homebrew/master/feat/Sample%20-%20Giddy%3B%20Magically%20Gifted%2C%20Whip%20Aficionado.json
This is a feature that is site-specific, but you will find that general concept from time to time - that a file link, instead of going to direct file, will bring up an embedded player, and that the player provides an option for a link to the direct file, or to download the file for use from a hosting service of your choice.
  • https://media.giphy.com/media/bcKmIWkUMCjVm/giphy.gif​​​​
    That's an animated .gif (see the ending bit of text? that says .gif -- the player doesn't use and cannot play animated gifs, if your file doesn't work, and ends in .gif, that's why.
     
  • https://i.imgur.com/zvATqgs.gifv
    That's the new animated .gif format .gifv.  (and in case you're wondering, renaming a file to .webm or mp4 won't make the file's "type" change - the file is written in a specific language/structure.  The player reads that language, and if its not in that language - it just doesn't work. 


By testing
This is the most obvious, but least used. Take the URL and try opening that URL in a different browser, you may also wish to have one of more players confirm that they can do can.}}


IMAGES
VIDEOS
Videos opened in the browser will open the video with a minimal set of controls. (See video below)
BrowserVideoVID.gif


It should not have a lot of ads, playlist, navigation or account management nav bar, or voting/rating system.
ie, not this.
YouTube labeled.png
AUDIO
Direct File URLS for audio will initiate either a file download or prompt the browser to start playing the file. (See sample screenshoot from a Chrome browser below).
AudioPage.png
JSON/Homebrew
When viewed through the browser it will looking like code listing in the browser.
(Example from a RAW address on GitHub.
GithubRAW.png


One/Some/All of my players cannot see/hear the animation/audio, but I can!

Troubleshooting
Check to see if the player(s) are using the supported environment, have the most current versions of the browser and extensions are installed, and configured correctly.
Most likely the URL you have chosen isn't a public address, and so your browser is playing it because YOU/your machine is authorized already to see that file, while your players are not.
Solution Steps:
Move the file to a place everyone has access to (see the specific feature for suggested locations) or by giving everyone access rights to that location.


Features that use this:

LibreAudio
Animated Background
External Art
Insert Token by URL
Paste image from URL
Import by Category; Module Importer/Exporter; Temporary Import



Related Features



Did that answer your question(s)?

If not please check the under Support; Troubleshooting or the Known Issues page for further guidance, or go to the Discord community and leave a comment in the issues channel.

If you enjoy the project, please follow this link to see how you can contribute and help make it even better.