Self-Hosting

npm package installation

Install the all-in-one package that includes both the core engine and UI components:

npm install @webplayer/webplayer

Or, if you use yarn or pnpm:

yarn add @webplayer/webplayer
pnpm add @webplayer/webplayer

Basic programmatic usage

Import and initialize WebPlayer in your JavaScript or TypeScript project:

import { WebPlayer } from '@webplayer/webplayer';

const player = new WebPlayer({
  container: document.body,
  theme: 'dark',
  autoplay: false,
  volume: 0.8,
  include: 'main',
});

// Initialize the player (scans the DOM and renders the UI)
player.init();

// You can also add tracks programmatically
player.playlist.addTrack({
  title: 'My Song',
  url: 'https://example.com/song.mp3',
  artist: 'Artist Name',
});

// Control playback
player.play();

Using @webplayer/core and @webplayer/ui separately

For more control, you can install the core engine and UI layer as separate packages. This is useful if you want to build a custom UI or use the engine without the default player interface:

npm install @webplayer/core @webplayer/ui

Use the core engine for playback without any UI:

import { EngineManager } from '@webplayer/core';
import { DomScanner } from '@webplayer/core';
import { Playlist } from '@webplayer/core';
import { EventBus } from '@webplayer/core';

// Create the event bus
const events = new EventBus();

// Scan the DOM for media links
const scanner = new DomScanner({ include: 'body', exclude: '' });
const tracks = scanner.scan();

// Create a playlist from detected tracks
const playlist = new Playlist(tracks, events);

// Create the engine manager for playback
const engine = new EngineManager(events);

// Play the first track
const track = playlist.getTracks()[0];
engine.load(track);
engine.play();

Add the UI components separately using Web Components:

import '@webplayer/ui';

// The UI registers custom elements: <wp-player>, <wp-controls>,
// <wp-progress>, <wp-playlist>, etc.
// Create the player element and append it to the page:
const playerEl = document.createElement('wp-player');
document.body.appendChild(playerEl);

Running your own backend

The WebPlayer backend provides API routes for YouTube search, oEmbed resolution, and AI-powered entity detection. Source code will be available on GitHub soon. In the meantime, use the npm packages for the client-side player.

Once the repository is public, you will be able to clone it and run the full backend locally:

git clone https://github.com/Tomorrow-You/webplayer.git
cd webplayer

# Install dependencies
pnpm install

# Set up environment variables (see below)
cp apps/web/.env.example apps/web/.env.local

# Start the development server
pnpm dev --filter=web

The backend exposes these API routes:

Point your widget to your own backend by setting apiBase in the configuration:

<script>
var WPParams = {
  apiBase: "https://your-domain.com"
};
</script>
<script src="https://your-domain.com/widget/loader.js" async></script>

Environment variables

The following environment variables are used by the backend API routes. Add them to your .env.local file:

# apps/web/.env.local
YOUTUBE_API_KEY=your-youtube-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
UPSTASH_REDIS_REST_URL=https://your-instance.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-redis-token