KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

shrimpcast

★ 46 Open GitHub ↗

A highly customizable, flexible, lightweight, battle-tested, fast and secure self-hosted streaming platform.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">
 Shrimpcast
</h1>

## Introduction

Shrimpcast is a highly customizable, flexible, battle-tested, high performance, and secure self-hosted streaming platform, built for resilience at scale to support thousands of users.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Troubleshooting](#troubleshooting)
- [Throughput estimation](#throughput-estimation)
- [Media server](#media-server)
- [Development](#development)
- [Usage](#usage)
  - [Getting started](#getting-started)
  - [How to set up your first stream](#how-to-set-up-your-first-stream)
  - [Configuration](#configuration)
    - [Site](#site)
    - [Chat](#chat)
    - [Stream](#stream)
    - [Poll](#poll)
    - [Tor & VPNs](#tor-and-vpns)
    - [Bingo](#bingo)
    - [OBS](#obs)
    - [Theme](#theme)
    - [Vapid](#vapid)
    - [Golden pass](#golden-pass)
    - [Turnstile](#turnstile)
    - [Load balancing](#load-balancing)
  - [Media server](#media-server)
  - [Bans](#bans)
  - [Mutes](#mutes)
  - [Auto-mod filters](#auto-mod-filters)
  - [Moderators](#moderators)
  - [Notify users](#notify-users)
  - [Emotes](#emotes)
  - [Bingo options](#bingo-options)
  - [Message and user management](#message-and-user-management)
  - [Chat commands](chat-commands)
    - [Cloud OBS](#cloud-obs)
    - [Whispers](#whispers)
    - [Others](#others)
- [Update](#update)
- [License](#license)

_Last revision: **2.0.8**_

## Features

- **Secure**
- **Strong anti-spam foundations**
- **Fast and lightweight**
- **Flexible and highly customizable**
- **Battle-tested with thousands of concurrent users**
- **Out-of-the-box Cloudflare support**
- **Feature rich**
- **Inbuilt load balancing**

## Installation

To install Shrimpcast, follow these steps:

> [!IMPORTANT]
> You need a valid domain to run this script, with properly configured DNS records.

> [!NOTE]
> Recommended OS: Ubuntu x64 22.04 LTS

> [!NOTE]
> While the exact hardware requirements depend on your workload, a minimum of 2 vCPUs and 4 GB of RAM is recommended.

1. On a fresh VPS, run:

```bash
   wget -O install.sh https://github.com/shrimpcast/shrimpcast/releases/latest/download/install.sh
   chmod +x install.sh
   ./install.sh -d [YOUR_DOMAIN_NAME]
   ```

Make sure to replace `[YOUR_DOMAIN_NAME]` with your domain name.
   
   Your instance will automatically reboot after the installation completes.
> [!IMPORTANT]
> SSL will be automatically configured. You **MUST** have properly configured DNS records before running the script.

2. (Optional) If you're using Cloudflare as a reverse proxy, run:

```bash
   wget -O cloudflare_setup.sh https://github.com/shrimpcast/shrimpcast/releases/latest/download/cloudflare_setup.sh
   chmod +x cloudflare_setup.sh
   ./cloudflare_setup.sh
   ```

This script will restrict traffic outside Cloudflare and apply a few required configuration tweaks.
   
> [!IMPORTANT]
> If you are using cloudflare, remember to set SSL to strict mode. Otherwise, cloudflare won't be able to connect to your origin.

And that's it! Shrimpcast should now be up and running. You can now try to access your domain URL. Make sure to save the admin session that was generated during the installation, which you can find by running 
```bash 
cat /root/shrimpcast/setup/GeneratedAdminToken.txt; echo
```
Or at the end of step 1.

## Troubleshooting

- .NET SDK installed but not found: run 
 ```bash
 sudo snap remove dotnet-sdk &&
 sudo apt remove -y 'dotnet*' 'aspnetcore*' 'netstandard*' &&
 sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list /etc/apt/sources.list.d/microsoft-prod.list.save &&
 sudo apt update &&
 sudo apt install -y dotnet8
 ```
 then add the `--skipdotnet` flag to the install script and re-run it: `./install.sh [...] --skipdotnet`
- Certbot fails: 
 Ensure that port 80 on your VPS is publicly accessible and that your domain’s DNS is correctly configured. Then run:
 ```bash
 sudo apt-get remove --purge nginx nginx-common &&
 sudo rm -rf /etc/nginx && 
 sudo apt-get autoremove --purge
 ``` 
 then re-run the install script.

## Throughput estimation
Accurately measure your server's actual upload speed:
```bash
sudo apt-get install curl
curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash
sudo apt-get install speedtest
speedtest
```

## Development

To build and debug the project, you will need:

- An IDE: **Visual Studio**, **VS Code**, or **Rider**
- **.NET 8 SDK and runtime**
- **PostgreSQL**
- **FFmpeg 6 or later**  
  *(On Windows, ensure FFmpeg is available on your system `PATH`)*

### Windows-only requirements

- Git
- Add Git’s `bin` directory to your system `PATH`  
  *(typically `C:\Program Files\Git\usr\bin`), as the project relies on several Bash utilities*

## Usage

### Getting started

Once you have Shrimpcast up and running, you will need to authenticate as an admin. To do this, use the token saved at `/root/shrimpcast/setup/GeneratedAdminToken.txt`, and follow these instructions:

1. Press the top-left button.
2. Paste the token and submit.

And that's it! You're now authenticated as an admin.

### Configuration

Once you're authenticated as an admin, you will have the following options:

<img width="408" height="35" alt="image" src="https://github.com/user-attachments/assets/73b38ffb-3a5f-4b1a-8518-a6207c18f600" /> 
 - [Configuration](#configuration)
 - [Site](#site)
 - [Chat](#chat)
 - [Stream](#stream)
 - [Poll](#poll)
 - [Tor & VPNs](#tor-and-vpns)
 - [Bingo](#bingo)
 - [OBS](#obs)
 - [Theme](#theme)
 - [Vapid](#vapid)
 - [Golden pass](#golden-pass)
 - [Turnstile](#turnstile)
 - [Load balancing](#load-balancing)
 - [Media server](#media-server)
 - [Bans](#bans)
 - [Mutes](#mutes)
 - [Auto-mod filters](#auto-mod-filters)
 - [Moderators](#moderators)
 - [Notify users](#notify-users)
 - [Emotes](#emotes)
 - [Bingo options](#bingo-options)

#### Site
<img width="1119" height="783" alt="iamge" src="https://github.com/user-attachments/assets/0532774e-53a0-4fb3-95af-fd955664fe3e" />

- **Enable PWA**: Toggles [Progressive Web App (PWA)](https://en.wikipedia.org/wiki/Progressive_web_app) support on or off.
- **Force latest version**: Forces all clients to be on the latest frontend version.
- **Publicly display connected users**: Shows or hides the list of connected users for non-admin users.
- **Max connections per IP**: The maximum number of simultaneous connections by a single IP address.
- **Minimum auto-mod time**: The minimum delay time expressed in milliseconds for the auto-mod.
- **Maximum auto-mod time**: The maximum delay time expressed in milliseconds for the auto-mod.
- **Open site at**: Time at which the site will be opened for users. While the site is closed, users will see a countdown:
  ![image](https://github.com/shrimpcast/shrimpcast/assets/167498236/4da09809-76ca-40dd-ba3f-d655480987f4)
- **Stream title**: The title of both the stream and site.
- **Stream description**: Site/stream description. Use \n for line breaks.

#### Chat
<img width="1273" height="849" alt="image" src="https://github.com/user-attachments/assets/ff7c4837-10f5-4380-a4b2-6055c4fe86bb" />

- **Enable chat:** Determines whether the chat feature is enabled or disabled for users.
- **Strip non ASCII characters:** Determines whether characters beyond the ASCII range, including Latin-A, may be used in chat messages.
- **Allow verified users only:** Specifies whether chat is restricted to verified users only.
- **Max visible messages:** Sets the maximum number of messages visible in the chat interface.
- **Message age limit (mins):** Specifies the age threshold of messages to display in the chat.
- **Required time for new users (min):** Sets the minimum time (in minutes) that new users must wait before being allowed to send messages.
- **Required time to post links (min):** Sets the minimum time (in minutes) that new users must wait before being allowed to send links. Use -1 for unlimited. 
- **Cooldown between messages:** Specifies the time interval users must wait between sending consecutive messages, in seconds.
- **Mute time in minutes:** Determines the duration for which a user is muted after violating chat rules.
- **Message length before truncation:** Defines the message length threshold at which it gets collapsed.
- **Default name for new users:** Sets the default username assigned to new users.

#### Stream
<img width="1600" height="666" alt="image" src="https://github.com/user-attachments/assets/d61ce80f-ce8b-4aa5-9a2a-fb869ea76792" />

- **Enable stream:** Shows or hides the player.
- **Show viewer count per stream:** Shows viewer count per stream.
- **Name:** Source name, also used for routing.
- **Title**: Optional source title displayed on the stream selection page. If left empty, the source name will be used instead.
- **URL:** URL source for the stream feed.
- **Thumbnail:** Determines the thumbnail used on the multistream preview for each source. If left empty, and the input is a server stream, the default generated thumbnail will used.
- **Legacy player**: Uses the browser’s native player for streaming. Also compatible with platforms like YouTube, Twitch, Streamable, and others.
- **Embed:** Dictates whether to treat URLs as embedded content.
- **With credentials:** Determines whether the player sends authentication cookies (HLS only). Use only if necessary.
- **UPD media on switch**: If enabled, the media server stream will adopt the same enabled state as the stream source when the scheduled start time is triggered. Note both the media server stream name & the source name need to have the same exact name.
- **Schedule start**: Schedules a background job to automatically enable the source. If already enabled, a countdown timer will be displayed.
- **Schedule end**: Schedules a background job to automatically disable the source.
- **Sort priority**: The numeric sort priority used to display streams in ascending order.

#### Poll
![image](https://github.com/user-attachments/assets/40d82667-cc50-41b8-b142-23260028102e)
- **Show poll:** Controls the visibility of the poll.
- **Accept new options:** Determines whether new options can be added to an existing poll.
- **Accept new votes:** Specifies whether new votes are allowed after a poll has started.
- **Make votes public:** Makes votes visible to all users.
- **Minimum sent to participate:** Sets the minimum number of messages a user must have sent to participate in a poll.
- **Poll title:** Specifies the title or topic of the poll being conducted.

#### Tor and VPNs
![image)](https://github.com/user-attachments/assets/f8aee1d3-524a-4fb5-b31c-d094ea051da3)
- **Block TOR connections site-wide:** Blocks access to the site for TOR users.
- **Block TOR connections (chat only):** Prevents TOR users from chatting, but they can still access the site.
- **Block VPN connections site-wide:** Blocks access to the site for VPN users.
- **Block VPN connections (chat only):** Prevents VPN users from chatting, but they can still access the site.
- **API URL for IP detection service:** The third-party service used for IP detection (default: ip-api.com).
- **API key for VPN detection service:** Optional field for a token if the IP detection service requires one.
- **Optional header for sending the API key:** Allows sending the API key in a custom header.
- **VPN detection match criteria:** Customize how the JSON response is matched (e.g., `{"proxy": (value), "hosting": (value)}`).

#### Bingo 
![image](https://github.com/user-attachments/assets/32a9a460-d2ac-4724-b426-d8a8dd3b22d6)
- **Show bingo:** Determines whether the bingo is displayed.
- **Enable auto marking:** Specifies whether automatic marking of options is enabled once a certain threshold is met.
- **Auto marking seconds threshold:** The number of seconds during which simultaneous suggestions are considered.
- **Auto marking unique user threshold:** The minimum number of unique user suggestions required to trigger auto-marking.
- **Bingo title:** A title for the bingo (self-explanatory).

#### OBS
![image](https://github.com/user-attachments/assets/72f665d9-1c13-44b9-b779-ea8546af281e)
> [!TIP]
> You don't need any of these configurations unless you're using a cloud OBS instance and you want to control it remotely. If you're going to use them, make sure that your OBS has WebSockets enabled and is accepting incoming connections. See more on [cloud OBS](#cloud-obs)
- **Host:** Specifies the host for OBS connection. Format: (ws://[IP]:4455)
- **Password:** Provides the password required for authentication when connecting to OBS.
- **Main scene:** Specifies the main scene to be displayed in the OBS interface.
- **Main source:** Specifies the main video source to be displayed within the main scene.
- **Kino source:** Specifies the video source to be displayed in the "Kino" scene.
- **Music source:** Specifies the audio source to be optionally played during the broadcast.

#### Theme
![image](https://github.com/user-attachments/assets/7bd254ed-84d3-42c3-bf40-2abd8cdb4a76)
- **Enable fireworks:** Toggles the display of fireworks animations.
- **Enable Christmas theme:** Enables or disables the Christmas theme.
- **Enable Halloween theme:** Enables or disables the Halloween theme.
- **Christmas theme snowflake count:** Specifies how many snowflakes are shown in the Christmas theme.
- **Primary color:** Sets the default primary palette color (default: blueGrey).
- **Secondary color:** Sets the secondary palette color (default: orange).

#### Vapid
![image](https://github.com/user-attachments/assets/40642056-f6e7-45f5-b55a-643c1e22c998)
> [!CAUTION]
> Do not change these values unless you know what you're doing.
- **VAPID Public Key:** Specifies the public key for VAPID authentication.
- **VAPID Private Key:** Specifies the private key for VAPID authentication.
- **VAPID Mail:** Provides the email address associated with VAPID authentication.

#### Golden pass
![image](https://github.com/user-attachments/assets/7621cd84-1fe5-45ce-80f9-99098e01e17b)
- Fully automated integrations with BTCPayServer & Stripe,

#### Turnstile
![image](https://github.com/user-attachments/assets/072a8c57-a9f8-413e-ac10-2325ba83d86f)
- Requires [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/) verification for new users.

#### Load balancing
<img width="1273" height="349" alt="image" src="https://github.com/user-attachments/assets/e0935596-9a45-46d0-866d-c0a34b48a906" /> 
- **Send metrics:** Specifies whether instance resource usage statistics are sent.
- **Master instance domain:** The domain to which metrics are reported. Format should be `domain.tld`. Do not include protocols or slashes.
- **Auth token:** The auth token used for metrics reporting. Must be the same on both master and slave instances.

### Load balancing setup

Set up your child instances on a subdomain (e.g., `lb(n).domain`), using the same auth token across all instances. Then enable sending metrics from each load balancing instance to the master instance domain.

### Configuring a load-balanced stream

To load balance a stream, configure a source using the following format:

```
[lbs]{settings}[/lbs]https://{subdomain}{lbi}.domain/..stream.../index.m3u8
```

---

### Load balancing modes

### 1. Instance count

Distribute traffic evenly across a fixed number of instances.

**Example:** balance across 5 instances (`lb1` through `lb5`):

```
[lbs]5[/lbs]https://lb{lbi}.domain/api/mediaserver/streams/stream/index.m3u8
```

> **Note:** All child instances must produce identical HLS output for this to work correctly.

---

### 2. Instance count with exclusions

Distribute traffic across a range of instances while skipping specific ones.

**Example:** balance across 5 instances, excluding `lb1` and `lb5` (uses `lb2`, `lb3`, `lb4`):

```
[lbs]ei5_1,5[/lbs]https://lb{lbi}.domain/api/mediaserver/streams/stream/index.m3u8
```

---

### 3. Weighted distribution

Steer traffic to specific instances by percentage.

**Example:** 50% to `lb1`, 20% to `lb2`, 10% each to `lb3`, `lb4`, and `lb5`:

```
[lbs]w50,20,10,10,10[/lbs]https://lb{lbi}.domain/api/mediaserver/streams/stream/index.m3u8
```   
  
## Media server

### RTMP Endpoints
Defines RTMP ingress and egress points. For example, you can configure an RTMP endpoint to receive a stream directly from **OBS**.

### Outputs
Generates high-performance **HLS** streams. Accepts a wide range of input formats including HLS sources, RTMP/SRT egress endpoints, **VOD**, and **FLV** — essentially any video-compatible source.  
If you intend to stream from an RTMP input, use the corresponding **RTMP egress URL**.

### Probe
Configures input settings. Supports **H.264/AAC** transcoding and custom audio sources.  
While transcoding is CPU-intensive, it ensures your input is properly encoded for playback across all devices.  
This is particularly useful for **VOD** inputs or sources that may contain corrupted or incompatible media.

### Bans
<img width="600" height="167" alt="image" src="https://github.com/user-attachments/assets/9d5ec050-3993-4c1e-be57-05c488e2dff5" />

Shows the list of banned users. Use the button on the right to unban a user.  
Format: `{[M]/[A] (manual/automod)} {name} {creation date} [all known token IPs]`

### Mutes
![image](https://github.com/shrimpcast/shrimpcast/assets/167498236/45a00624-5b5e-4456-999f-0a1ea85697e0)

Shows the list of currently muted users. To remove a mute, use the button on the right.

### Auto-mod filters
<img width="600" height="267" alt="image" src="https://github.com/user-attachments/assets/b945836a-4a53-469d-bf4b-287c8cbf8eaf" />

Shows the list of active auto-mod filters. Use the button on the right to remove them.
- **Ignore case**: ignores letter casing in the given string. For example, for `test`, `TEST` and `tEsT` will all match.  
- **Ignore accents**: ignores diacritics in the given string. For example, for `test`, `tést` and `teśt` will all match.

### Moderators
![image](https://github.com/shrimpcast/shrimpcast/assets/167498236/9f9183d5-f3ee-4086-9f9c-7eb54725ebe0)

Shows the list of moderators. Use the button on the right to unmod them.

### Notify users
![image](https://github.com/shrimpcast/shrimpcast/assets/167498236/cfd0c047-277f-4fce-b399-6356e165392c)

Shows a dialog asking whether to notify the subscribed users that the stream has started.

### Emotes
![image](https://github.com/shrimpcast/shrimpcast/assets/167498236/fb6d898c-a218-420c-96e0-d86ae10c205b)

Shows the list of active emotes. To add a new emote, click on "ADD". Keep in mind that the size can't be greater than 36x36.

### Bingo options
![image](https://github.com/user-attachments/assets/4853a1c9-7ecb-44c1-93d8-fc02c8f6a50c)

Shows the list of bingo options. To add a new option, click on "ADD".

### Message and user management
<img width="319" height="40" alt="image" src="https://github.com/user-attachments/assets/9ec8a14d-2342-40a7-9c7e-0c52225bee81" />

While authenticated as an admin, hover over a message and you will have the options to:
1. Remove the message (by clicking on the remove button)
   
   ![image](https://github.com/shrimpcast/shrimpcast/assets/167498236/7e718ae2-ed98-43e7-bd64-261e7383d030)
   
2. Manage the user (by clicking on the user button)
   
   ![image](https://github.com/user-attachments/assets/02d83a4b-87fa-4a06-838c-b8fbd7e21fa5)

The following moderation options will be available:
   - **Make mod**: Grants the user moderator privileges.
   - **Verify**: Verifies the user.
   - **Ignore**: Ignores the user. This option is available to all users.
   - **Mute**: mutes the user for the amount of time dettermined in the chat [configuration](#chat)
   - **Ban**: Bans the user and displays a public chat message indicating that the user has been removed from chat.
     >Caution: when issuing a ban, all IPs associated with the user will be blocked.  
   - **Silent ban**: Bans the user without notifying the chat.
   - **Silent ban and delete**: Issues a ban and removes the user messages without notifying the chat.
   - **Filter and ban**: Same as **Silent ban and delete**, but also adds the message to the auto-mod filters
> [!WARNING]
> The auto-mod tool isn't intended for censorhip but to ease the removal of spam. Note that adding a filter will result in any user whose message contains the filter being banned.

## Chat commands

### Cloud OBS

If you're utilizing a cloud OBS instance, manage it effortlessly through chat commands:

- `!playmain [URL?]`
- `!playkino [URL?]`
- `!playmusic [URL?]`

### Whispers

Admins can securely send private messages to users using the following chat command:

- `!ping [SessionId] [Message]`

Retrieve the SessionId from the [Message and User Management](#message-and-user-management) section.

#### Others
- `!resetallsavedvpnrecords` — Clears all saved VPN-related IP records.
- `!tryipservice [IP?]` — Tests the IP service. If no IP is provided, it defaults to the requester’s IP.
- `!redirectsource [FROM] [TO]` — Redirects users watching source `FROM` to source `TO`.

# How to set up your first stream

Go to the [media server](#media-server) and set up a stream:

<img width="1542" height="189" alt="image" src="https://github.com/user-attachments/assets/243d5cb6-4d79-4035-8652-0d29cf16973d" /> 
- **Enabled:** Specifies whether the stream is enabled.
- **Name:** The name of the stream.
- **Ingress URL:** The input media URL. Can be any supported media type, including VOD. To read from RTMP (for example if you'd like to use OBS), you must first set up an RTMP endpoint (see [RTMP endpoints](#rtmp-endpoints)).
- **HLS segment length:** HLS segment duration in seconds. Cannot be lower than 2.
- **HLS list size:** HLS playlist length. Cannot be lower than 6.
- **Thumbnail interval:** Specifies how often a thumbnail is generated, in seconds. Minimum is 15 seconds.
- **Watermark URL:** A watermark that is hard-burned into the top-right of the stream. Requires transcoding to be enabled.
- **Subtitles URL:** Subtitles that are hard-burned into the stream. Requires transcoding to be enabled.
- **Start time:** The timestamp at which media playback starts. Useful for VOD.

Then, click `RUN PROBE` to probe the URL: 
<img width="600" height="417" alt="image" src="https://github.com/user-attachments/assets/b03f48b8-4d00-4344-be5f-791c0aa08c49" /> 
- **Treat input as HLS:** Specifies whether to force the input to be treated as HLS when the content type cannot be automatically determined. Useful, for example, when using a plain-text M3U8 file with a different extension.
- **Custom headers:** Custom HTTP headers to include with the request (for example, `Referer`).

Once your stream is up and running, go to the active stream processes panel and click `Preview`. 
<img width="1150" height="122" alt="image" src="https://github.com/user-attachments/assets/51029f71-011f-49cc-bd14-b13c887d13c2" />
Then click on `copy` 
<img width="900" height="65" alt="image" src="https://github.com/user-attachments/assets/4bb1efe7-c5c3-4991-9997-f5ecbb8be996" />

You now have a stream up and running. You can now go to [sources](#stream) and use your URL as the input.

# Playlists
<img width="1542" height="253" alt="image" src="https://github.com/user-attachments/assets/5cf51b21-7c10-4625-963e-594c63c3d725" />
<img width="600" height="189" alt="image" src="https://github.com/user-attachments/assets/a60f65fb-4446-462b-a663-ec3cbd947734" />

You can create playlists from media streams. For example, given sources like movie1, movie2, and movie3, you can add them as a comma-separated list to a playlist ( ``movie1,movie2,movie3`` ).

## Update
If you want to update to the latest version of shrimpcast, you can do so by running
   ```bash
   wget -O update.sh https://github.com/shrimpcast/shrimpcast/releases/latest/download/update.sh
   chmod +x update.sh
   ./update.sh -d [YOUR_DOMAIN_NAME]
   ```
   Make sure to replace `[YOUR_DOMAIN_NAME]` with your domain name.

## License

This project is licensed under the [GNU License](LICENSE).

shrimpcast

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README