These are the broad steps to using the On Air sign:
- Create a Google API project to get a YouTube Data API token to enter into your secrets.py file
- Get the Channel ID of the YouTube channel you want to monitor, this will go into the code.py
- Set the operating hours you want to check for livestreams. The YouTube Data API allows about 100 queries per day of the streaming status, so we need to limit the hours checked to concentrate that query power. This way, we can still check every few minutes.
YouTube Token
To prevent unwanted bot traffic, Google requires each query of the YouTube stats to be accompanied by a YouTube token.
First, you'll need to get set up with your YouTube Data API key. Follow these instructions to get this set up.
On the next page, give your project a name, such as Matrix-YouTube-Streaming and then click CREATE. (Ignore the project name in the graphic)
Next, click the + ENABLE APIS AND SERVICES link at the top of the page.
Now, you'll be able to click the Library link on the left hand side so you can select the YouTube Data API v3 from the available libraries.
Choose the YouTube Data API v3 item from the first dropdown menu.
In the second menu, choose Other non-UI (e.g. cron job, daemon)
Then, click the Public data radio button.
Finally, click the What credentials do I need? button to get your API key.
One last setting to enable - click on the API restrictions tab for your API key and set the dropdown to YouTube Data API v3. Then click Save.
Your credentials will be generated and you should now copy the Key value and paste it into your secrets.py file.
Here's how to enter the token into your secrets.py file.
secrets = {
'ssid' : '_your_wifi_ssid_',
'password' : '_your_wifi_password_',
'aio_username' : 'your_adafruitIO_username',
'aio_key' : 'your_ginormous_AIO_key',
'youtube_token' : 'HUGE_LONG_YOUTUBE_API_TOKEN'
}
JSON
To keep things current, the stats are grabbed from the Google APIs website itself.
Google automatically generates a JSON file for each YouTube channel, in this case at the address: https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=UCpOlOeQjj7EsVnDh3zuCgsA&type=video&eventType=live&key=YOUR_HUGE_LONG_YOUTUBE_API_TOKEN (Be sure to replace that last part with your actual token!)
This file contains all sorts of information, delivered in an easy-to-parse format. If you visit that URL in Firefox, you'll see the JSON data it returns. You can look at the "beautified" version and the raw data to compare by clicking the buttons at top.
Here it is in a raw-er form, but still using indentation and carriage returns to make it readable:
{
"kind": "youtube#searchListResponse",
"etag": "-4wUWjFHBk38Khg9K18Hz94OcyU",
"regionCode": "US",
"pageInfo": {
"totalResults": 0,
"resultsPerPage": 5
},
"items": []
}
When the channel is not broadcasting a livestream, the items key will contain no data. Here's what this page will look like when there is a livestream happening:
{
"kind": "youtube#searchListResponse",
"etag": "gLr84DV9iftEnLHwS-d7TBzFqhA",
"regionCode": "US",
"pageInfo": {
"totalResults": 1,
"resultsPerPage": 5
},
"items": [
{
"kind": "youtube#searchResult",
"etag": "VKDTVQVYQDRDxvl-7WObsEXSCbc",
"id": {
"kind": "youtube#video",
"videoId": "20XZOCmf4ts"
},
"snippet": {
"publishedAt": "2020-08-05T02:19:17Z",
"channelId": "UC6p-tjZN8s9GBSbiN4K-bwg",
"title": "testing stream",
"description": "",
"thumbnails": {
"default": {
"url": "https://i.ytimg.com/vi/20XZOCmf4ts/default_live.jpg",
"width": 120,
"height": 90
},
"medium": {
"url": "https://i.ytimg.com/vi/20XZOCmf4ts/mqdefault_live.jpg",
"width": 320,
"height": 180
},
"high": {
"url": "https://i.ytimg.com/vi/20XZOCmf4ts/hqdefault_live.jpg",
"width": 480,
"height": 360
}
},
"channelTitle": "John Park",
"liveBroadcastContent": "live",
"publishTime": "2020-08-05T02:19:17Z"
}
}
]
}
Keys
If we look through the JSON file, we'll see a key called items with a sub-tree below it. When the broadcast is off air, this key will be empty, but when it is on air, there is a lot of data there. In our code we can therefore tell when the broadcast is live based on the contents of the items key.
Our CircuitPython code is able to check for data using this variable:
DATA_LOCATION1 = ["items"]
You can get your own Channel ID by logging in to YouTube and then going to your advanced account settings page.
There, you'll see your YouTube Channel ID, which you can copy and paste into the code.py file's CHANNEL_ID variable to track that channel's stats.
Text editor powered by tinymce.
