BitPlay Documentation

If you have Go installed, you can run BitPlay directly from the source code.

Prerequisites:

• Go 1.18 or later

Steps:

1. Clone the repository and enter the directory.
2. Download the necessary Go modules.
3. Run the application using go run.

The server will start on http://localhost:3347 by default.

You can run the BitPlay container directly using the docker run command.

Steps:

1. (Optional) To persist settings, create a local config directory: mkdir -p ./config.
2. Run the container with the following command. Use the -v flag only if you created the directory in step 1.
3. Access the UI at http://<your-server-ip>:3347.

# (Optional) Create the config directory for persistence
mkdir -p ./config

# Run the container
docker run -d \
  --name bitplay \
  -p 3347:3347 \
  # Add the volume mount below ONLY if you want persistent settings (and created ./config above)
  -v $(pwd)/config:/app/config \
  --restart unless-stopped \
  ghcr.io/aculix/bitplay:main

Once the application is running and configured, follow these steps to stream content:

1. Configure Settings: Set up your proxy and search providers (Prowlarr/Jackett) in the Web UI.
2. Search: Use the search bar to find torrents via your configured providers.
3. Add Torrent: Click a search result or paste a magnet link directly.
4. Stream: Select a video file from the loaded torrent info to start streaming in the built-in player.

Docker Compose is the recommended method for deployment. This setup allows you to optionally mount a local directory to ensure your settings (Proxy, Prowlarr, and Jackett configurations) persist across container restarts.

Prerequisites:

• Docker
• Docker Compose

Steps:

1. Create a docker-compose.yml file with the configuration below.
2. (Optional) If you want persistent settings, create the config directory on your host first: mkdir -p ./config.
3. Start the container using docker-compose up -d.
4. Access the UI at http://<your-server-ip>:3347.

services:
  bitplay:
    image: ghcr.io/aculix/bitplay:main
    container_name: bitplay
    ports:
      - 3347:3347 # Expose the web UI port
    volumes:
      # Mount the config directory for persistent settings (Optional)
      - ./config:/app/config 
    restart: unless-stopped

BitPlay is configured through its web interface. Settings are automatically saved to /app/config/settings.json inside the container (or your mounted host directory).

Configuration Options:

• Proxy: Enable/disable and provide a full SOCKS5 proxy URL (e.g., socks5://user:pass@host:port). Note: HTTP proxies are not supported.
• Prowlarr: Enable/disable and provide the Prowlarr Host URL (e.g., http://prowlarr:9696) and your Prowlarr API Key.
• Jackett: Enable/disable and provide the Jackett Host URL (e.g., http://jackett:9117) and your Jackett API Key.

Each setting includes a test button to verify the connection.

BitPlay supports opening a torrent or magnet link directly via a URL query parameter named torrent. The value must be URL-encoded.

Example Pattern: http://localhost:3347?torrent=<URL_ENCODED_MAGNET_OR_TORRENT_LINK>

BitPlay uses a Settings struct to manage application configuration, which is persisted in config/settings.json. You can configure proxy settings and search provider settings (Prowlarr or Jackett) via the API.

Key configuration fields include:

• enableProxy: Boolean to enable/disable SOCKS5 proxy.
• proxyUrl: The URL of the proxy server.
• enableProwlarr / prowlarrHost / prowlarrApiKey: Settings for Prowlarr integration.
• enableJackett / jackettHost / jackettApiKey: Settings for Jackett integration.

To add a new torrent to a streaming session, send a POST request to /api/v1/torrent/add with a JSON body containing the magnet link.

If the provided URL is an HTTP link (e.g., from Prowlarr or Jackett), the server will attempt to follow the link/redirect to extract the actual magnet URI. If successful, it initializes a TorrentSession and returns a sessionId used for streaming.

Search for torrents through a Prowlarr instance by sending a GET request to /api/v1/prowlarr/search?q=[query].

This endpoint requires Prowlarr host and API key to be configured in the settings. It returns a simplified list of results including title, magnetUrl (or downloadUrl), size, seeders, leechers, and indexer.