73 lines
4.9 KiB
Markdown
73 lines
4.9 KiB
Markdown
# 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
|
|
```
|
|
|
|
## 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. |