owncast-clipper/README.md

# 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. 

## ✅ 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](#-configuration).

### 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).

## ⚙️ 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](#peertube-channel-id). | **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](#owncast-access-token). | **Yes** |
| CLIP_DIRECTORY | The directory where source .ts files from owncast will be collected. /var/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
```yaml
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
```


CLIP_DIRECTORY, TEMP_DIRECTORY, CLIP_QUANTITY = None, None, None
PEERTUBE_HOST, PEERTUBE_USER, PEERTUBE_PASS = None, None, None
OWNCAST_HOST, OWNCAST_AUTH = None, None
AUTHENTICATION_REQUIRED, PT_API_BASE, PEERTUBE_CHANNEL_ID = None, None, None