Django application for multimedia annotations facilitating collaboration on video and image analysis. Developed at the Columbia University Center for Teaching and Learning.
JavaScript Python HTML CSS Gherkin Makefile Other
Latest commit 88fd45f Feb 20, 2017 @thraxil thraxil committed on GitHub Merge pull request #1241 from ccnmtl/raven-6.0.0
⬆️ raven 6.0.0
Failed to load latest commit information.
apache Django 1.7 - 1st pass Mar 27, 2015
docs Update features inline with common test data Apr 27, 2016
lti_auth django 1.10 style Aug 10, 2016
media Update juxtapose to 6e15863f4decbaa1c8d4904b8cae186e874709f2 Feb 16, 2017
mediathread Update juxtapose to 6e15863f4decbaa1c8d4904b8cae186e874709f2 Feb 16, 2017
requirements ⬆️ pip 9.0.1 Feb 17, 2017
scripts remove stashed sqlite3 database Apr 27, 2016
structuredcollaboration speed up collaboration Sep 13, 2016
.coveragerc PEP8 violations Jan 14, 2015
.dockerignore docker setup Nov 30, 2015
.gitignore Added DS_Store in list to be gitignored Jan 13, 2017
.jscsrc add make targets for jshint and jscs Sep 22, 2014
.jshintrc Add jshint checking to sherd code Nov 4, 2015
.travis.yml ⬆️ firefox 45.3.0esr Aug 2, 2016 initial code of conduct and contributing guidelines Oct 30, 2015 😍 Oct 30, 2015
Dockerfile revive the docker/docker-compose setup May 11, 2016
LICENSE add .edu to my email Sep 8, 2016
Makefile that didn't work Aug 19, 2016
README.markdown revive the docker/docker-compose setup May 11, 2016 Use mediathread-bookmarklet package instead of sherd - PMT #103485 Nov 2, 2015 ⬆️ 1.1.0 Nov 8, 2016
docker-compose.yml docker setup Nov 30, 2015 docker setup Nov 30, 2015 use standard/versioned makefiles Apr 29, 2016 use standard/versioned makefiles Apr 29, 2016 use standard/versioned makefiles Apr 29, 2016 Move to Django 1.4.5 Jun 1, 2013
package.json ⬆️ jscs 3.0.7 Nov 4, 2016
requirements.txt Merge pull request #1241 from ccnmtl/raven-6.0.0 Feb 20, 2017 AnnotationList: retune to avoid id conflict Nov 16, 2016 Django 1.7 - 1st pass Mar 27, 2015



Build Status

Mediathread is a Django site for multimedia annotations facilitating collaboration on video and image analysis. Developed at the Columbia Center for New Media Teaching and Learning (CCNMTL)

CODE: (see wiki for some dev documentation)


Python 2.7 Postgres (or MySQL)
Flowplayer installation for your site (See below for detailed instructions)
Flickr API Key if you want to bookmark from FLICKR


  1. Clone Mediathread

    git clone

  2. Build the database
    For Postgres (preferred):
    A. Create the database createdb mediathread

    For MySQL: (Note: Mediathread is not well-tested on recent version of MySQL.)
    A. Edit the file requirements.txt
    - comment out the line psycopg2
    - uncomment the MySQL-python line.

    B. Create the database

    echo "CREATE DATABASE mediathread" | mysql -uroot -p mysql

  3. Customize settings
    Create a file in the mediathread subdirectory. Override the variables from that you need to customize for your local installation. At a minimum, you will need to customize your DATABASES dictionary.

    For more extensive customization and template overrides, you can create a deploy_specific directory to house a site-specific file:

     $ mkdir deploy_specific
     $ touch deploy_specific/
     $ touch deploy_specific/

    Edit the deploy_specific/ and override values in like the DATABASES dictionary. This is where we add custom settings and templates for our deployment that will not be included in the open-sourced distribution.

  4. Build the virtual environment Bootstrap uses virtualenv to build a contained library in ve/


The rest of the instructions work like standard Django. See: for more details.

  1. Sync the database

    ./ migrate

  2. Run locally (during development only) ./ runserver

Go to your site in a web browser.

  1. The default database is not very useful. You'll need to create a course and some users. Login with the superuser you created in Step #5.

  2. Click the 'Create a Course' link.

    • Click the "+" to make a group. Name it something like "test_course"
    • Click the "+" to make a faculty group. Name it something like "test_course_faculty"
      • In the "Add users to group" field...
        • add yourself as a faculty member by putting your username with a "" in front like this "admin"
        • add some fellow faculty/student accounts -- you can create new accounts right here (read the instructions under the textarea)
      • Click "Save" and then click the upper-right link "Django administration" to get back to the regular site (yeah, not the most intuitive).
  3. Experiment with saving assets by visiting:


[Please note that the docker setup for Mediathread is still experimental. There are likely to be rough edges here.]

If you have docker set up and docker-compose installed, you can get a development environment up and running very quickly. To initialize it, the following steps are recommended:

$ make build
$ docker-compose run web migrate
$ docker-compose run web manage createsuperuser

After that, a simple:

$ docker-compose up

will bring up a development server on port 8000 (if you are running boot2docker, it may end up on a different port) backed by a PostgreSQL database.

If requirements have been updated, you can rebuild the image by re-running make build. Eventually, we'll be automatically publishing the Mediathread Docker image to the Docker Hub and you will instead be able to just run docker pull ccnmtl/mediathread to update.

The usual Django commands can be run inside the docker compose container like so:

$ docker-compose run web manage help
$ docker-compose run web manage shell

(Note that it's with manage, not; this is the custom entrypoint script ( at work.)

You can run the unit tests inside the container with the following command:

$ docker-compose run web manage test --settings=mediathread.settings

That one's a little tricky and unintuitive. Normally, running Mediathread inside the container via docker compose, it will use the settings file, which contains the configuration for connecting to the PostgreSQL instance running in the other container. For unit tests, you don't want that though, so the command above explicitly sets it back to the default dev settings.

Production deployment with Docker is also possible, though even less tested than development. The file has the default settings that the docker image uses and is designed to allow you to override/set the important values through environment variables (so configuration can be kept out of the docker image).


Mediathread makes use of the Django Sites framework.

By default, Django creates a site called "" with an id of 1. This id is referenced in as SITE_ID=1.

In your production environment, RENAME to your domain.

If a new site is created, update SITE_ID= in your deploy_specific/ or


ALLOWED_HOSTS is "a list of strings representing the host/domain names that this Django site can serve. This is a security measure to prevent an attacker from poisoning caches and password reset emails with links to malicious hosts by submitting requests with a fake HTTP Host header, which is possible even under many seemingly-safe web server configurations." More here:

Make sure the ALLOWED_HOSTS is set properly in your deploy_specific/ or


For deployment to Apache, see our sample configuration in apache/sample.conf. This directory also contains standard django.wsgi file which can be used with other webservers


To support bookmarking assets from a variety of external sites, Mediathread instances must be accessible via http:// and https://


Mediathread instantiates a Flowplayer .swf or HTML5 player to play many video flavors. Flowplayer requires you to have a local installation and will not allow you to serve the player off their site. Free versions exist for both players. Here are the basic instructions to install Flowplayer on your systems and point Mediathread at it.

  1. Both versions are available here.
  2. Install both versions on a public server on your site.
  3. In the same directory as the Flash player, also install: - flowplayer.rtmp-3.2.13.swf - flowplayer.pseudostreaming-3.2.13.swf -

  4. In your or (better) deploy_specific/ set FLOWPLAYER_SWF_LOCATION, like so:
    FLOWPLAYER_SWF_LOCATION= 'http://servername/directory/flowplayer-3.2.15.swf' FLOWPLAYER_HTML5_LOCATION = 'http:///flowplayer-5.5.0/flowplayer.min.js'
    FLOWPLAYER_PSEUDOSTREAMING_PLUGIN = 'flowplayer.pseudostreaming-3.2.11.swf'
    FLOWPLAYER_RTMP_PLUGIN = 'flowplayer.rtmp-3.2.11.swf'

  • For Flash, the plugins are picked up automatically from the same directory, so don't need the full path.
  • These are the versions we are currently using in production here at CU.


In your or (better) deploy_specific/ specify your Flickr api key.


Mediathread's About & Help pages are constructed using the Django Flat Pages architecture. ( In order to setup pages for your site, follow these steps:

  1. Navigate to the Mediathread /admin/ area, Flatpages.

  2. Create a new flat page, e.g. url: /help/ or /about/, select your domain site site and add content.

  3. Save.

  4. The page should be immediately available by navigating to yourdomain/help/ or yourdomain/about/


Our help documentation tailored for the Columbia community and our in-house video upload system is here:

And, Nate Autune helpfully added this a few months ago, "Thanks to Rebecca Darling from Wellesley College, who graciously gave permission to re-publish her "Mediathread Guide for Students" under a Creative Commons license. Here is a link to where you can download it:"


  1. Current development on the Mediathread bookmarklet is aimed at supporting the standard set forth by ( This format includes a system of hierarchal terms and their associated values. Use of the metadata terms itemscope, itemtype, and itemprop are used to help stucture the data such that Mediathread can make sense of what metadata is assocaited to the item or items being brought into the application. Examples of this structure can be found here:

  2. Use the Google Rich Snippet test tool to test your structure:

  3. It is also worth noting that the LRMI (Learning Resource Metadata Initiative) has been working with in creating a more robust set of property (itemprop) terms that have been accepted into the standard. Some of these terms may be useful in determining what might best describe a data set or collection. Here is a link to this new specification: