search

tfabris / CrowCam

A set of Bash scripts to control and maintain a YouTube live cam from a Synology NAS.
GNU General Public License v3.0
4 stars 3 forks source link

readme

CrowCam

© 2024 by Tony Fabris

https://github.com/tfabris/CrowCam

CrowCam is a set of Bash scripts which control and maintain a webcam in my backyard. The scripts automate some important tasks which would otherwise be manual and repetitive, and also work around some unfixed bugs in the streaming software and in YouTube itself. Including:

This project could be useful to anyone who uses a Synology NAS, running the Synology Surveillance Station app, to stream a camera to YouTube, but who might have encountered the same problems with it that I did. It's also a good platform for demonstrating some useful programming techniques. These scripts include well-documented methods for the following things:

Table of Contents

Project Information

The CrowCam is a webcam we use to watch the local crows that we feed in our backyard. We like to feed them because they are friendly, intelligent, playful, entertaining, and they recognize faces. We've even written songs about them.

It is an IP security camera connected to our Synology NAS, which uses the Synology Surveillance Station app to record a live feed of the camera. We then use the "Live Broadcast" feature of Surveillance Station to push the video stream to our YouTube channel, where anyone can watch.

This project is a set of related Bash script files, primarily these:

These script files will be installed to the Synology NAS, where they will be launched repeatedly, at timed intervals, using the Synology "Task Scheduler" feature.

Requirements

Setup of your YouTube live stream is not documented here. See the YouTube and Synology documentation to set this up. First make sure that the camera, NAS, Synology Surveillance Station, and "Live Broadcast" features are all working correctly, and that you can see the stream on your YouTube channel. Then you can begin setting up these scripts.

What Each Script Does

The main scripts in this archive are configured to run on an automatic timer on the Synology NAS. The scripts are:

CrowCam.sh

This script has multiple purposes:

CrowCamCleanup.sh

This script cleans up old archives:

Configuration

Obtain and unzip the latest files:

Edit configuration file:

Edit the file named "crowcam-config" (no file extension), and update the first several variables in the file. These are values which are unique to your installation. They are clearly documented in the file.

Edit thumbnail file:

Edit the file named "crowcam-thumbnail.jpg" to be your default thumbnail that is used when a new video stream is created. This must be a JPG that adheres to the YouTube standards for thumbnail files. Make sure to change it to something that is appropriate for your YouTube channel! The file I've included in the source code is the one for my YouTube channel, and I'm sure you don't want that.

Create Synology API credentials file:

Create an API credentials file named "api-creds" (no file extension), containing a single line of ASCII text: A username, a space, and then a password. These will be used for connecting to the API of your Synology NAS. Choose an account on the Synology NAS which has a level of access high enough to connect to the Synology API, and which has permission to turn the Synology Surveillance Station "Live Broadcast" feature on and off. The built-in account "admin" naturally has this level of access, but you may choose to create a different user for security reasons. Create the "api-creds" file and place it in the same directory as these scripts.

If you have trouble with the API user, then look here for details of a Synology API user permissions bug, including details of a workaround: https://github.com/tfabris/CrowCam/issues/90

Obtain YouTube OAuth credentials:

OAuth credentials are used for giving these scripts permission to access the YouTube account, so that it can do things such as clean up old video stream archives and check on the status of the stream. You should only need create these credentials once, unless something goes wrong or you revoke the credentials.

Run preparation script, to authorize your YouTube account:

Run the CrowCamCleanupPreparation script. This script will authorize the Google developer OAuth credentials (created above) to make changes to the YouTube stream, and then will obtain an all-important refresh token which will allow it to continue doing it over time, without needing to keep re-authorizing. You should only need to run this script once, unless the tokens get invalidated or there is an unexpected error. Open a Bash shell on your local PC, in the same folder as these scripts. Then set the file permissions and launch the preparation script using these commands:

 chmod 770 CrowCam*.sh
 chmod 770 crowcam-config
 chmod 660 client_id.json
 ./CrowCamCleanupPreparation.sh

The preparation script will display some messages. Follow its prompts on the screen, and make sure to follow all instructions and answer all promtps correctly. If done correctly, a file should now be created in the same directory as these scripts, named "crowcam-tokens" (no file extension).

Copy script and configuration files to the NAS

Once the preparation script has run successfully, then create a folder named "CrowCam" on your the Synology NAS, in the folder /volume1/homes/admin/ by doing the following:

Copy the following files from your local PC into the folder on the NAS:

 CrowCam.sh
 CrowCamCleanup.sh
 CrowCamHelperFunctions.sh
 crowcam-config
 crowcam-override-config    (if you created one)
 api-creds
 crowcam-tokens
 crowcam-thumbnail.jpg
 client_id.json

Once all these files are copied to the NAS, then SSH into the NAS:

 ssh admin@192.168.0.222      # (update the address to be your NAS address)

Set the access permissions on the folder and its files, using the SSH prompt:

 chmod 770 CrowCam
 cd CrowCam
 chmod 770 CrowCam*.sh
 chmod 770 crowcam-config
 chmod 770 crowcam-override-config
 chmod 660 api-creds
 chmod 660 crowcam-tokens
 chmod 660 crowcam-sunrise
 chmod 660 crowcam-sunset
 chmod 660 crowcam-thumbnail.jpg
 chmod 660 client_id.json

Create automated tasks in the Synology Task Scheduler

In the Synology Control Panel, open the Task Scheduler, and create the following tasks, each task should have the following settings:

Usage and Troubleshooting

The scripts should now be running via the Synology Task Manager.

You can monitor the Synology Log Center, over a long period of time, to see if the scripts are running OK. The scripts will not put much information into the Log Center unless something goes wrong. When working correctly, they will not be very chatty there, though expect to see messages in the following situations:

To troubleshoot a script, or to see more details about how a script is working, SSH into the Synology and run it from the shell. From there, you can see all the "dbg" level messages which aren't shown in the Synology system log.

Steps for preparing to debug one of the scripts:

You can then do one or both of the following:

Note that when the script is running from the Synology Task Scheduler, it will run under the account "root", which is different from the account that it will run under when you are logged in with an SSH prompt. So some differences may occur. For example, the script may write a temporary file called "wgetcookies.txt" to store cookies when accessing the Synology API, and the file might end up in different locations. If running the script directly at the SSH prompt, the file will end up in that directory, but if running under Synology Task Scheduler, the file will end up in the "/root" folder.

Also, feel free to configure the script to one of the other debugMode settings, to test it on a local Windows or Mac computer, and run the script there. The debug mode has some limitations when running under Windows or Mac, and will skip certain commands and features if debugged in those states.

Note: Don't leave the debugMode flag set for a long time. The scripts don't work fully if the debugMode flag is set. For example, the Cleanup script will only log its intentions in debug mode, but won't actually clean up any files. When you are done troubleshooting, remember to set the debugMode flag back to normal, copy it back to the Synology, and re-enable the script in the Synology Task Scheduler.

Resources

YouTube OAuth script examples and information:

YouTube API samples:

YouTube Video API references:

Google Developer Console:

Ideas for how to parse the Json results from the Curl calls:

Synology API references:

Acknowledgments

Many thanks to the multiple people on StackOverflow, whose posts were invaluable in answering many questions, and giving me syntax help with Linux Bash scripts. Many thanks to the members of the empegBBS who helped with everything else that I couldn't find on StackOverflow. Thanks Mlord, Peter, Roger, Andy and everyone else who chimed in.

Thanks, all!