owncast-clipper

A simple and single-purpose bot which provides a clip command to Owncast stream viewers and automatically uploads to a specified PeerTube instance. A functional work-in-progress.

🖱️ Usage

Once installed and configured, the clipper bot will silently sit in chat, waiting for a viewer to type !clip <title>. Once uploaded to PeerTube, a link to the clip will be posted in chat as the clipper bot user.

If a title is provided, it will be used as the title of the clip in PeerTube. If not, the clipper's disply name and a timestamp will be used instead.

✅ Preparation

Beyond easily-discoverable information such as user credentials and base URLs, there are two pieces of information needed which non-technical users may struggle with: the Owncast Access Token and the PeerTube channel ID.

Owncast Access Token

Can be found by visiting the Integrations -> Acess Tokens page of the Owncast Admin at admin/access-tokens/:

1. Visit the Access Tokens page of your Owncast Admin interface. If your instance is https://stream.person.site, the page may be found at https://stream.person.site/admin/access-token.
2. You'll need to Create an Access Token and name it appropriately (something like "Clip Bot" is a good starting point). It will require the "Can send chat messages on behalf of the owner of this token" permission.
3. Once the token is created, you'll be able to retrieve it by clicking on the eye icon to unhide the token, then copying and pasting into the OWNCAST_AUTH variable as described below.

PeerTube Channel ID

This one is a little trickier to get, because the value that we need isn't directly exposed via the UI. Here's what to do:

1. Go to your Channel (not User) page on PeerTube. If your PeerTube instance is https://peertube.video.site, and your channel name is Cool Channel, you should have a URL like this: https://peertube.video.site/c/cool_channel/videos.
2. You want the part of the URL between the /c/ and /videos: in this case: cool_channel.
3. Adjust the following URL to match your environment and open it in your browser: https://peertube.video.site/api/v1/video-channels/cool_channel.
4. Your browser may or may not format the raw data, but you're looking for the first instance of "id" in the response. If your browser is showing you raw data, you can just do a text search for "id".
5. The number immediately following "id" is your Channel ID! Copy and paste it into your PEERTUBE_CHANNEL_ID variable as described below.

⚙️ Configuration

At the moment, configuration is performed exclusively through environment variables.

Variable	Description	Required
PEERTUBE_HOST	The base URL for the PeerTube server we're uploading to, e.g. https://peertube.video.site	Yes
PEERTUBE_USER	The username of the account authorized to post to PeerTube	Yes
PEERTUBE_PASS	The password of the account authorized to post to PeerTube	Yes
PEERTUBE_CHANNEL_ID	The internal "channel id" of the PeerTube channel we're uploading clips to. Described above.	Yes
OWNCAST_HOST	The base URL for the PeerTube server we're making API calls against, e.g. https://coolstream.site or http://app:8080	Yes
OWNCAST_AUTH	A valid Owncast Access Token, with access to the User Chat scope. Described above.	Yes
CLIP_DIRECTORY	The directory where source .ts files from owncast will be collected. /app/data/hls/0/ by default.	No
TEMP_DIRECTORY	The directory where intermediate remuxed .mp4 files will be stored. /tmp/ by default.	No
CLIP_QUANTITY	The maximum number of segment files to attempt to collect to make a clip. 20 by default.	No

Example docker-compose.yml

version: '3'

services:
  owncast:
    image: gabekangas/owncast:latest
    user: 1000:1000
    restart: unless-stopped
    ports:
      - 1935:1935
    volumes:
      - ./data/owncast:/app/data

  clipper:
    image: code.mch.onl/ety/owncast-clipper:latest
    user: 1000:1000
    restart: unless-stopped
    depends_on:
      - owncast
    volumes:
      - ./data/owncast:/app/data:ro
      - type: tmpfs
        target: /tmp
    environment:
      - PEERTUBE_HOST=https://video.peertube.site # your PeerTube server
      - PEERTUBE_USER=your_peertube_username
      - PEERTUBE_PASS=SuperSecretPassword
      - PEERTUBE_CHANNEL_ID=1502
      - OWNCAST_HOST=http://owncast:8080 # internal or fully-qualified Owncast server
      - OWNCAST_AUTH=AReallyLongOwncastAccessTokenString # Owncast access token with chat permission

Considerations

At the moment, this project is mostly intended to be run in a docker compose context alongside an existing owncast installation, because that matches my deployment. If there's interest in updating this project to run standalone, this can probably be done, I just didn't want to spend the effort on it yet without any interest.

Becauase the permissions on the Owncast hls folder are restrictive, it's easiest if you force both the owncast and owncast-clipper containers to run as the same user. If your Owncast instance already exists and you haven't been running it as a specific user already, you may need to chown your owncast directory to the new service user.