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. 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](#-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. `/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
```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
```

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