README

Composer package allowing to easily import video's from a YouTube channel into a Blue Billywig VMS publication.

NOTE

All video's must be publicly accessible.

DISCLAIMER

Youtube-dl does not use the YouTube API but scrapes web pages to collect data from the YouTube videos. This could cause youtube-dl or this package to stop working without notice.

Getting Started

Requirements

This package uses the command line software youtube-dl under the hood. This piece of software must be installed on your computer in order to use this package. To install youtube-dl, follow these instruction here.

In order to communicate with the Blue Billywig API a shared secret is required. A shared secret can be generated by going to https://YourPublication.bbvms.com/ovp/#/publication/api-keys (where YourPublication needs to be substituted with the name of your publication) and clicking CREATE NEW KEY.

Why youtube-dl? Why not use the YouTube API directly?

In order to communicate with the YouTube API, a special API key is required. In order to obtain such a key, one needs to create a Google account, create a project inside the Developer Console and then follow some elaborate instructions. On top of that, one is only able to make x amount of requests (for free) using this key.

Since there is a security risk involved as well as a limit to the amount of API calls that can be made using the YouTube API key, it is not feasible to include a YouTube API key with this package.

Since it is a pain to force you to create a Google account and make you jump through hoops in order to create a YouTube API key, this package uses youtube-dl instead. Yes, that does require you to install an extra piece of software on your computer but, it is easier to install and delete than a Google account. Also, youtube-dl does not only work with YouTube but with hundreds of other sites as well.

All in all, youtube-dl is the more flexible and open-ended solution to gather information from the video's on your YouTube channel.

Usage

Include bluebillywig-youtube-importer into your project

In the root of your project run the following command:

composer require wmrsp/bluebillywig-youtube-importer

Downloading metadata

<?php

require dirname(__FILE__) . "/vendor/autoload.php";

use wmrsp\BlueBillywig\YouTubeImporter\Importer;

$youtube_url = "https://www.youtube.com/user/myawesomeusername";
$publication_name = "YourPublication";
$publication_shared_secret = "123-1234567890abcdefghijklmnopqrstuv";

$importer = new Importer($youtube_url, $publication_name, $publication_shared_secret);

$importer->downloadYouTube();

This will download a json file for each video on your YouTube channel/account. These json files contain information about the YouTube videos, amongst which the url of the particular video. In the next step this url will passed on to the Blue Billywig API so that the video may be imported into your Blue Billywig VMS account.

The order in which the video's are imported into the Blue Billywig VMS is the order in which the json files reside in the downloads folder ../vendor/wmrsp/bluebillywig-youtube-importer/downloads.

Importing into the Blue Billywig VMS

<?php

require dirname(__FILE__) . "/vendor/autoload.php";

use wmrsp\BlueBillywig\YouTubeImporter\Importer;

$youtube_url = "https://www.youtube.com/user/myawesomeusername";
$publication_name = "YourPublication";
$publication_shared_secret = "123-1234567890abcdefghijklmnopqrstuv";

$importer = new Importer($youtube_url, $publication_name, $publication_shared_secret);

// FALSE may be passed as a parameter to the 'importDownloads' method in order to skip the duplicates check.
// This check will make sure that the video to be imported has not already been imported into the Blue Billywig VMS before.
// In most cases TRUE would be the desired setting in order to prevent duplicate video's in your VMS environment.
$import_results = $importer->importDownloads(TRUE);

print_r($import_results);

This will extract the video's url from each of the json files and pass it onto the Blue Billywig API, which in turn will import the video into the VMS. When it is all set and done the import results will be returned and saved in a log file in the logs folder ../vendor/wmrsp/bluebillywig-youtube-importer/logs.

With every successful import, the corresponding json file will be removed from the downloads folder. However, the log file will not be removed. It may be used for later reference.

Please do keep in mind that, in order to prevent overloading the Blue Billywig API, there is a timeout of 30 seconds in between the import of each video.

Full example

<?php

require dirname(__FILE__) . "/vendor/autoload.php";

use wmrsp\BlueBillywig\YouTubeImporter\Importer;

$youtube_url = "https://www.youtube.com/user/myawesomeusername";
$publication_name = "YourPublication";
$publication_shared_secret = "123-1234567890abcdefghijklmnopqrstuv";

$importer = new Importer($youtube_url, $publication_name, $publication_shared_secret);

$importer->downloadYouTube();
// FALSE may be passed as a parameter to the 'importDownloads' method in order to skip the duplicates check.
// This check will make sure that the video to be imported has not already been imported into the Blue Billywig VMS before.
// In most cases TRUE would be the desired setting in order to prevent duplicate video's in your VMS environment.
$import_results = $importer->importDownloads(TRUE);

print_r($import_results);

Retrieving import results

The result of every video that is imported is logged in the log file. These results can be retrieved from the log file as an array using the getLogAsArray method of the Importer object.

<?php

require dirname(__FILE__) . "/vendor/autoload.php";

use wmrsp\BlueBillywig\YouTubeImporter\Importer;

$youtube_url = "https://www.youtube.com/user/myawesomeusername";
$publication_name = "YourPublication";
$publication_shared_secret = "123-1234567890abcdefghijklmnopqrstuv";

$importer = new Importer($youtube_url, $publication_name, $publication_shared_secret);

$import_results = $importer->getLogAsArray();

print_r($import_results);

If desired, the import results as of a certain date (ignoring all import results from before that date) can retrieved from the log file by passing an instance of the DateTime object to the getLogAsArray method.

<?php

require dirname(__FILE__) . "/vendor/autoload.php";

use wmrsp\BlueBillywig\YouTubeImporter\Importer;
use DateTime;

$youtube_url = "https://www.youtube.com/user/myawesomeusername";
$publication_name = "YourPublication";
$publication_shared_secret = "123-1234567890abcdefghijklmnopqrstuv";
$as_of_date = new DateTime("Monday last week");

$importer = new Importer($youtube_url, $publication_name, $publication_shared_secret);

$import_results = $importer->getLogAsArray($as_of_date);

print_r($import_results);

Unit Testing

To run the PHP unit tests, copy tests/config.example.yaml to tests/config.yaml and update tests/config.yml with the settings that apply to your publication.

Run the tests with the following commands.

./vendor/bin/phpunit --bootstrap ./vendor/autoload.php ./vendor/wmrsp/bluebillywig-youtube-importer/tests/ImporterTest.php