This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description
.. image::

Clarify Brightcove Sync Tool

Automatically send your Brightcove data to Clarify.

This is a simple tool for sending the content of a Brightcove ( video library to Clarify (, including the media and metadata.

The Clarify API analyzes media for words spoken and makes it searchable. It can also automatically generate extra metadata such as keywords and topics.

Running the sync tool will compare the contents of your Brightcove library and your Clarify account app. Any new videos will be added as a new bundle in Clarify, with the media and metadata from Brightcove. Videos that have been updated in Brightcove since the last sync will have their corresponding bundle metadata updated in Clarify. Any bundles that no longer have a corresponding video will be deleted (after prompting the user to confirm the delete.)

This script does not modify content in Brightcove so does NOT require Brightcove API write access.

* Requires Python 3 (yeah!)
* If you have a very large or rapidly changing video library, see `Limitations`_ below.
* Free software: MIT license


This script requires Python 3.4 or above. Make sure the pip you are running corresponds to Python 3.x and not Python 2.x.

.. code-block:: bash

$ pip install clarify_brightcove_sync

You may need to use sudo if you don't have permission to install. If you are upgrading from an older version, use the --upgrade flag.

Quickstart Guide

You must configure the authentication credentials for your Brightcove and Clarify accounts.

Brightcove Credentials

To get Brightcove API credentials:

* Log in to
* In the ``ADMIN`` menu, choose ``API Authentication``
* Click ``Register New Application`` button
* This will bring up a form
+ In the ``Name`` field enter ``Clarify Brightcove Sync``
+ Select your account for authorization
+ Enable the ``Video Read`` permissions for the CMS API
+ Click Save
+ Copy the ``Client Secret`` and store it in a safe place
+ Copy the ``Client ID`` and store it in a safe place as well
* Now go back to the ``ADMIN`` menu and choose ``Account Information``
* Copy your Account number, we will use it in the next steps.

Now we have the credentials we need to store them in a config file:

* Open a new file in your editor and enter the following text
.. code-block::

"account": "",
"client_id": "",
"client_secret": ""

* Fill in the values for the ``Account`` number, ``Client ID``, and ``Client Secret``.
* Save the file as ``brightcove_oath.json``
* Set an environment variable ``BRIGHTCOVE_API_CREDENTIALS`` with the path to the ``brightcove_oath.json`` file. This path can be relative to the current working directory. Alternatively, you can pass the value on the commandline when you run the script as ``BRIGHTCOVE_API_CREDENTIALS=<file> clarify_brightcove_sync``.

Clarify Credentials

* Log in to the Clarify developer portal
* Go to ``Apps & Keys`` and copy the API Key for your app
* Set an environment variable ``CLARIFY_API_KEY`` with the value of your key. Alternatively, you can pass the value on the commandline when you run the as ``CLARIFY_API_KEY=<secret> clarify_brightcove_sync``.
.. code-block:: bash

$ export CLARIFY_API_KEY=secret_key

Running the Script

It is recommended to run the script from a shell / command prompt. Make sure you are running Python 3.x and your environment is set up properly.

If everything is configured properly, you can simply run the following command to do a dry-run of a sync. This won't actually modify any data.

.. code-block:: bash

$ clarify_brightcove_sync --dry_run

or if you are passing the credentials on the commandline:

.. code-block:: bash

$ CLARIFY_API_KEY=<secret> BRIGHTCOVE_API_CREDENTIALS=<file> clarify_brightcove_sync --dry_run

If things look correct, you can run the sync for real to have Clarify bundles created, updated, and deleted as needed. Note that this will incur usage of credit in your Clarify account.

.. code-block:: bash

$ clarify_brightcove_sync

Video Media

The Clarify API ingests media from URLs. This sync tool looks in the Sources (renditions) of a Brightcove Video to find one with the highest resolution (up to 1080p), encoded using the H264 codec, and featuring an http/https Src URL. If no suitable video URL is found, the bundle will not be created in Clarify. See `Limitations`_ for more details.


Video metadata from the Brightcove API is stored as Clarify bundle metadata so that it is searchable along with the spoken words. The following fields are created in the Clarify metadata:

.. code-block::

"name": "Sample Video 1",
"created_at": "2016-01-12T17:06:39.284Z",
"updated_at": "2016-01-29T17:44:26.340Z",
"state": "ACTIVE",
"description": "A sample video of a bird flying."
"long_description": "You'll never look at a bird the same way after you've seen this video.",
"tags": [

The state field corresponds to the Video's state (``ACTIVE`` or ``INACTIVE``) in Brightcove. If you use this flag, you can limit Clarify searches to only active videos by using a ``filter`` on the ``state`` field in your search request. See for more information.



In order to keep things simple and allow the script to work without Brightcove API write access, when the script starts it fetches the all the video metadata from the Brightcove library and all the bundle data from Clarify. It then compares these to know what needs updating. This has several implications:

* If the video library is too large, the sync will be slow and may lead to timeouts. It should be fine for libraries up to several thousand videos.
* If the Video metadata is updated frequently in Brightcove, this will cause the bundle metadata to also be updated frequently.
* Videos should not be deleted from Brightcove during a sync. Due to pagination in the Brightcove API, deleting a video may result in a still existing video to not be fetched and the sync tool will think the corresponding Clarify bundle should be deteled. Note that the sync tool will always prompt you before deleting a bundle. Creation of new videos and updates to videos are fine to do during a sync but they will not get picked up until the next sync is run.

To overcome the above limitations, the script could be improved by using the Brightcove API in write mode. Each Video could have a ``custom_field`` containing the bundle href/id of the Video's corresponding bundle in Clarify. Then the Brightcove API could be used to search for the Videos that need changing, for example videos with no bundle href/id set.

The iteration/pagination issue could be resolved by refetching the video library until the video count matches the expected count.

Video Media

The Clarify API ingests media from URLs. This sync tool looks in the Sources (renditions) of a Brightcove Video to find one with the highest resolution (up to 1080p), encoded using the H264 codec, and featuring an http/https Src URL. If no suitable video URL is found, the bundle will not be created in Clarify. Currently, the tool only supports videos that were ingested with Brightcove and does not support "remote" videos.

Support for remote videos could be easily added. If the ``remote`` field in the Video Source is ``true``, the Brightcove CMS Asset API can be used to get the Rendition list, and from that the ``remote_url`` of the desired rendition. This URL can be used for the Clarify bundle.

Custom Fields

Currently the custom fields are not used in the Clarify metadata. An improvement to this script would allow you to specify a list of custom fields that would be mapped to bundle metadata fields.

History (Change Log)

See `HISTORY.rst <history.rst>`_


See `LICENSE <license>`_


0.0.1 (2016-01-29)

* Initial version
Release History

Release History


This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
clarify_brightcove_sync-0.0.1.tar.gz (10.5 kB) Copy SHA256 Checksum SHA256 Source Jan 29, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting