⚠️ IMPORTANT

Version 2 of Ceres, named "Ganymede" has been released. It is a complete re-write of the Ceres application in Golang with many improvements. Ceres will no longer be supported. Visit the Ganymede repository for more information.

---

Ceres

Archive Twitch Streams and VODs with a rendered chat.

---

v0.0.6 Update

Archiving live streams is finally here! Update v0.0.6 brings support to archive both the video stream and the chat of a live stream. Check out the wiki page for more information.

---

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
   • Logging In
   • Archiving
   • Monitoring
3. Troubleshooting
4. FAQ
5. License
6. Acknowledgments
7. Contact

About

ceres_preview.mp4

Ceres is an application for downloading and viewing past Twitch streams and VODs. Ceres uses Lay295's TwitchDownloader to download the video and render the chat. All archived vods are downloaded locally to keep forever.

Downloaded data is saved in a user friendly way allowing you to keep and browse your archived vods without needing Ceres. Below is the folder structure for channel and VOD data.

/mnt/vods/
├── asmongold/
│   ├── 1042411777/
│   │   ├── 1042411777_video.mp4
│   │   ├── 1042411777_chat.mp4
│   │   ├── 1042411777_chat.json
│   │   ├── 1042411777_info.json
│   │   ├── 1042411777_thumbnail.jpg
│   │   └── 1042411777_web_thumbnail.jpg
│   ├── 1043421343/
│   │   └── ...
│   ├── 1046683902/
│   │   └── ...
│   ├── asmongold_profile.png
│   └── asmongold_offline_banner.png
├── mizkif/
│   ├── mizkif_profile.png
│   └── mizkif_offline_banner.png
├── esfandtv/
│   ├── esfandtv_profile.png
│   └── esfandtv_offline_banner.png
└── staysafetv/
    ├── staysafetv_profile.png
    └── staysafetv_offline_banner.png

Getting Started

Prerequisites

• Linux environment with Docker and Docker Compose installed.
• Optional Network share mounted for VOD storage (ex /mnt/vods).
• 50gb+ free space for downloading VODs before moving them to final destination.
• Twitch application for the client id and secret.
  • Create an app here. Anything can be supplied for the name and callback url.

Installation

Download a copy of the docker-compose.yml and the nginx.conf files.

1. Edit the environment variables and paths. Below are snippets of the env vars and paths from each service that need to be changed.

Ceres

# ENV
DB_PASSWORD=CHANGEME                  # openssl rand -hex 24
JWT_SECRET=CHANGEME                   # openssl rand -hex 24
CLIENT_ID=CHANGEME                    # Twitch Client ID
CLIENT_SECRET=CHANGEME                # Twitch Client Secret
API_URL=CHANGEME                      # Http URL to Ceres API (this service) - example http://10.10.10.1:3950 or https://api.ceres.domain.com
LIVE_CRON_SCHEDULE=EVERY_5_MINUTES    # **Optional** Change the frequency of the live channel check (default 5 minutes). Visit https://github.com/Zibbp/Ceres/wiki/Changing-the-Live-Stream-check-cron-job for more information

# Volumes
/path/to/your/vods:/mnt/vods  # Change the path to where you vods are stored such as a network share (E.g. /mnt/nas/media/vods:/mnt/vods)

Ceres-Frontend

# ENV
API_URL=CHANGEME        # Http URL to API service (same url used above)
CDN_URL=CHANGEME        # Http URL Nginx service (http://10.10.10.1:3952 or https://cdn.ceres.domain.com)
NODE_ENV=development    # If hosting locally (http://IP) use development. If using SSL on a domain set to production to use secure cookies

Ceres-DB

# ENV
POSTGRES_PASSWORD=CHANGEME  # Same password set in the ceres service

Ceres-CDN

# Volumes
/path/to/nginx.conf:/etc/nginx/nginx.conf:ro  # Full path to the nginx conf
/path/to/your/vods:/mnt/vods                  # Full path to your vod storage location, same as the path in the ceres service

2. Bring up the services docker-compose up -d.

Logging In

Visit the frontend (default port is 3951) and log in with the default credentials.

Username: admin
Password: adminadmin

Once logged in please secure your account by doing one of the following.

• Changing the admin password
• Creating a new account and using the admin account to give your new account admin permissions then deleting the admin account from your account.

Archiving Your First VOD

1. Find a Twitch VOD and copy the ID from the URL (should be a string of numbers like 1249966495).
2. Navigate to the "Archive" page and enter the VOD ID.
   • Once the ID is entered, click out of the input field to preview the VOD title, thumbnail, duration, and date.
3. Click "Archive".

Monitoring the Progress

After archiving a VOD you will be redirected to the "queue" page. Here you can view the log of the video download, chat download, and chat render.

Troubleshooting

Missing images on the frontend

This is likely because the CDN_URL environment variable for the frontend is wrong. It should point the the Nginx service.

Frontend unable to connect to the API

Ensure the API_URL environment variable is correctly set in both the frontend and api service.

What to do when an archive job fails?

If an archiving job fails it will need to be restarted from the beginning. At the moment restart steps have not been added so the queue item and vod entry needs to be deleted from the admin panel. Once both have been removed the the VOD can be submitted for archive again.

FAQ

Can I be notified when a VOD is archived?

Yes, under your profile a webhook url can be added to send a webhook when a VOD you submitted is archived.

License

Distributed under the GNU General Public License. See LICENSE for more information.

Acknowledgments

• Lay295's TwitchDownloader <-- Awesome utility!

Contact

Discord - Zibbp#2560

Email - On Github Profile