Simple self-hosted audio streaming for the web

PL-10 is an open-source, simple, and customizable audio streaming server and website designed for smaller labels, artists, hobbyists, and projects. It provides an opportunity for learning and exploration in the fields of web and audio applications.

Just drop your files in the media folder and start the server.

This project is designed to be a learning and starter kit for developing your own project. Some care should be taken when using it for in a production environment as security and privacy concerns are not thoroughly considered. It may also not be suitable for high-traffic environments. If you have a lot of fans, you might want to send them to a different service (like the forthcoming Subvert).

With a little work, PL-10 could function well to promote your music.

• Demo
• Usage
• Setup
• Startup
  • Build the server
  • Start the server
• Configuration
  • Set the page title
  • Set the page subtitle
  • Set the supporting text
  • Media Directory
  • Maximum file number
• Customization
  • Front End
  • Back End
• Embedding in a web page, blog, etc
• Libraries and other references

There is an interactive demo running at: https://pl-10.x.burns.fm

Note: the machine its running on is not suited for large audiences, so performance may not be ideal.

Install all of the dependencies:

npm install

There is a page (/embedded/preview) that allows you to set up an embedded player with a username and password, otherwise it will be visible to all users who know about the route.

NOTE If you enable this without setting the username and password, the default credentials will be used. These are logged to the console on startup and change every time you restart the server.

Set the environment variable PL_10_PREVIEW_AUTH=true

Set the variables:

• Username: PL_10_PREVIEW_USER="<username>"
• Password: PL_10_PREVIEW_PASS="<password>"

Once the packages are installed you'll need to build the server code and start it up.

Note on Docker use: While there is a Dockerfile, and it should work for many cases, you may need to make adjustments to allow it to work properly for your server if that's your preferred deployment method. There are a couple of relevant npm commands you and view in the package.json file.

npm run build:server

If you start the server and the buttons don't seem to do anything, you probably forgot to to this step.

npm run build:client

If you want to rebuild the styles only then run

npm run build:client:styles

or the code only

npm run build:client:scripts

If you want to see your changes on the page as you edit the styles, then while your server is running, run this command in another terminal window to auto-compile your styles every time you save:

npm run watch:client:styles

Start the server in production mode

npm start

Start the server in development mode

npm run start:dev

This will enable additional logging if you're running into any trouble. It might help diagnose the problem.

npm run start:debug

Did you know? (Turning on the homepage route)
You can use the provided preview homepage as a template and customize it to suit your record release, or whatever your project is. It is disabled by default, and won't show unless you set an environment variable PL_10_USE_HOMEPAGE to true. You can do this from your command line as in the example below, or in your shell environment's configuration.
export PL_10_USE_HOMEPAGE=true

Some settings configuration is possible if you want to make some minor changes to how things are run.

• Set the page title
• Set the page subtitle
• Set the supporting text
• Media Directory
• Maximum File Number

Note: The custom values below have a limited set of characters they can support. Characters like double-quotes ("), dollar signs ($), and others will need to be 'escaped' in order to work correctly. For that reason, if you want more flexibility then you should edit the template file directly.

The splash template: `/views/includes/splash.ejs`

If you want to use the default layout and set the title text, use the following environment variable PL_10_PAGE_TITLE.

Use this for the main page text. Ideal for an artist name or album name, or short promo text. It will also be used for the browser page title (that will show up on the tab).

If you want to use the default layout and set the subtitle text, use the following environment variable PL_10_PAGE_SUBTITLE.

Use this for an artist name or album name. Something like that.

If you want to use the default layout and set the supporting text, use the following environment variable PL_10_SUPPORTING_TEXT.

Use this if you have some extra info you want to include like a promotional tagline, shout-out, or release date.

If you want to use the default layout and set the copyright text, use the following environment variable PL_10_COPYRIGHT.

The copyright symbol and date are already set for you, so just add any more text you'd like.

Note: To change this text in more detail, you can edit the footer template: /views/includes/footer.ejs

© 2023 <your-text-here>. All rights reserved.

You can set an alternative media directory by setting the environment variable PL_10_MEDIA_DIR to where your files are stored. Not all file types are supported yet. See: server/constants.ts

While the server could theoretically stream any audio file type that includes parse-able metadata, the client code relies on browser compatibility and not all file types are guaranteed to work with every browser. So, Pl-10 by default tries to work with as many browsers as possible for audio playback. You can change those settings if it suits your project.

By default, the server has a maximum number of files it will pick up. You can override that number by setting PL_10_MAX_FILES to a different number.

You can change anything in the application to suit your needs in as much detail as you'd like. The styles and code are laid out with intention and in a modular way to make finding your way around pretty easy.

• See the readme

If you are familiar with JavaScript, HTTP, NPM workflows, then you should find changing the backend functionality relatively simple.

In-depth documentation won't be included with PL-10 at launch, but if you know what you're doing, the best starting point is the set of scripts in package.json and the files in the ./server folder.

• See the readme (forthcoming)

PL-10 now supports embedding a player. You can use the direct URL, or set one up using the previewer. You can also make a request to the API for new embed code HTML.

To embed the player, point an iframe or a popup window at <your-pl-10-base-url>/embedded

Demo: https://pl-10.x.burns.fm/embedded

To set up an HTML embed code, go to <your-pl-10-base-url>/embedded/preview

There you can set the height/width and an optional track ID if you want it to start on a specific song.

Demo: https://pl-10.x.burns.fm/embedded/preview

You can get a preset HTML code without using the previewer. Send the height, width, and/or track ID as query parameters.

Make the request to <your-pl-10-base-url>/embed-code

Set a query parameter by adding one of the following to your url. Learn more about query parameters

You'll receive a JSON response that looks like this:

{
  "html": "<iframe width=\"888\" height=\"333\" src=\"http://localhost:8347/embedded\"></iframe>"
}

Demo: https://pl-10.x.burns.fm/embed-code

This project uses several open source fonts, code libraries, and icon sets.

If you need to understand how to work with some of the files included, you might find more information in the list below.

Some images are included for demo and display purposes. Except for noise.png and the Canada Wordmark, the images are owned by Rob Fairley and Burns Recording Company and should not be redistributed without permission. Feel free to share the cover art included, provided it's unmodified.

© 2022-2023 BRC