Metadata-Version: 2.1
Name: offstream
Version: 1.0.2
Summary: Personal twitch stream recorder
Home-page: https://github.com/soylent/offstream
Author: soylent
Author-email: 
License: UNKNOWN
Keywords: twitch,streaming
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask (~=2.0)
Requires-Dist: ipfshttpclient (~=0.8.0a2)
Requires-Dist: sqlalchemy (~=1.4)
Requires-Dist: streamlink (~=3.0.3)
Provides-Extra: test
Requires-Dist: pytest (~=6.2) ; extra == 'test'
Requires-Dist: pytest-cov (~=3.0) ; extra == 'test'
Requires-Dist: python-dotenv (~=0.19) ; extra == 'test'
Requires-Dist: types-requests (~=2.26) ; extra == 'test'
Requires-Dist: sqlalchemy[mypy] (~=1.4) ; extra == 'test'

# offstream

Record your favorite twitch streams automatically and watch them later.

- There is no web UI, just use curl and your favorite video player.
- Streams are recorded as is, without re-transcoding.
- Recordings are never muted.
- Ads are optional.
- You can run it on Heroku (completely free) or your own server.
- Recordings are stored on IPFS.
- RSS feed of all recordings is available. It can be consumed by youtube-dl,
  VLC, and other feed readers.
- Streams are available while recording is in progress.

## Installing

### Heroku

You can deploy the app to Heroku by clicking the button below and following the
instructions. IMPORTANT: When the app is deployed, click on the "View" button at
the bottom to complete the setup.

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/soylent/offstream/tree/v1.0.1)

### Local installation

1. Install the package.
   ```sh
   $ pip install offstream
   ```
1. Setup your local sqlite database located at `~/.offstream/offstream.db`.
   ```sh
   $ offstream setup
   ```
   You will get credentials to control the app. I recommend adding them to your
   `~/.netrc` file (or `_netrc` on Windows):
   ```
   machine <your-app-hostname>
       login offstream
       password <your-password>
   ```
1. Start the app.
   ```sh
   $ offstream
   ```

## Usage

Next, add your favorite streamers.

```sh
$ curl -n https://your-app-name.herokuapp.com/streamers -d name=garybernhardt
$ curl -n https://your-app-name.herokuapp.com/streamers -d name=esl_sc2 -d max_quality=720p60
```

The `max_quality` parameter is optional and defaults to `best`. Typical stream
quality options are <br>
`audio_only`, `160p`, `360p`, `480p`, `720p`, `720p60`, `1080p60`, `best`.

When any of the streamers goes live, the app will record the stream.

Finally, to watch the latest recording, open the following URL in mpv, VLC,
QuickTime, or any other video player.

```sh
$ mpv https://your-app-name.herokuapp.com/latest/esl_sc2
```

An RSS feed of all recordings is available at `https://your-app-name.herokuapp.com/rss`.

## API

- `POST /streamers -d name=<name> -d max_quality=<quality>`

  Track a new streamer.

  Requires auth.

- `DELETE /streamers/{name}`

  Delete a streamer. WARNING: Deletes all associated recordings too.

  Requires auth.

- `GET /latest/{name}`

  Get the latest recorded stream.

- `POST /settings -d ping_start_hour=<hour> -d ping_end_hour=<hour>`

  Modify ping settings. On Heroku, offstream keeps itself awake 24/7 by pinging
  itself periodically. You can save some dyno hours by changing the
  `ping_start_hour` and `ping_end_hour` settings to let the app sleep when no
  one is streaming.

  Requires auth.

- `GET /rss`

  RSS feed of all recordings.

## Configuration

The following environment variables are supported.

- `OFFSTREAM_FLUSH_THRESHOLD`

  Default: automatically calculated, normally `100000000` bytes (100M).

- `OFFSTREAM_CHECK_INTERVAL`

  Default: `120` seconds

- `OFFSTREAM_IPFS_API_ADDR`

  Default: `/dns/ipfs.infura.io/tcp/5001/https`

- `OFFSTREAM_IPFS_GATEWAY_URI_TEMPLATE`

  Default: `https://{cid}.ipfs.infura-ipfs.io/{path}`

- `OFFSTREAM_MAX_CONCURRENT_RECORDERS`

  Default: `5`

- `DATABASE_URL`

  Default: `sqlite:///$HOME/.offstream/offstream.db`

- `TZ`

  Preferred timezone, e.g. `America/New_York`. Please see<br>
  https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List

## FAQ

- Q: My video player reports the following error:<br>
  `keepalive request failed for 'https://bafybeie3v6lomkfti2b4zsa4yj35nypojllvjrzpbzyxhn5tkfoqaswmbm.ipfs.infura-ipfs.io/18846.ts'`

  A: This warning can be safely ignored. It's because Infura keeps the root
  content identifier (CID) in a subdomain, rather than in the path portion of
  the URL.

## See Also

Please also check out the [streamlink](https://streamlink.github.io/) project.


