Tutorial: Shaka Player Development

Quick Setup (TL;DR)

To get started quickly, just run ./build/all.sh and skip this document.

Checking Out a Specific Release

You can check out a specific release version after cloning the repository. Just use "git checkout" followed by a release, such as "git checkout v1.2.0".

Closure, Annotations, and the Build Process

The Shaka Player library was designed to be compiled with Google's open-sourced JavaScript compiler, Closure. The Closure compiler produces JavaScript code which is minified, optimized, obfuscated, and stripped of dead code. Deploying a Closure-compiled JavaScript library saves bandwidth, and the browser can also load and parse the code faster.

Closure also enforces structure and type-safety on the JavaScript language. It allows developers to annotate code with type information. The compiler can use this information to optimize the code, but it also helps catch bugs early, such as missing arguments, arguments of the wrong type, typos in names, etc.

The annotation syntax is derived from JSDoc. This means that the annotated code is also self-documenting. We generate docs based on these annotations using JSDoc. For information on annotation syntax, please refer to Annotating JavaScript on Closure's site.

The Closure compiler and JSDoc are both included in the source. To compile the Shaka Player library, simply run ./build/all.sh from the source root. Compiled JavaScript will be output to shaka-player.compiled.js in the source root.

To generate documentation, run ./build/docs.sh from the source root. Docs will be output to ./docs/api/ in HTML format.

The Test App

The project includes a test application which we used for manual testing during development. The test app is made up of index.html, index.css, and app.js, and can be accessed by pointing a web server at your source code checkout.

Many of the settings in the test app can be controlled with URL parameters such that the page can be reloaded without the need to manually change settings. To see a canonical list of URL parameters, see app.js.

Some parameters require a value, but most are boolean. The behavior of boolean parameters is activated by presence. Parameters are separated by semicolons.

  • lang=LANG - Changes the language preference fed to the library. Language settings use language tags from BCP 47, such as "en", "en-US', "fr-CA", "el", "deu-AT", etc.
  • nocenc - Select the non-encrypted version of the default sample.
  • vp9 - Select a VP9 DASH sample.
  • dash - Auto-play the selected DASH stream.
  • compiled - Load the library in compiled mode. See "Loader" below.
  • debug - Set the log level to show debug messages.
  • v - Set the log level to show debug and verbose messages.

Example URLs for the test app:

  • https://localhost/shaka/?nocenc
    • Defaults the UI to a non-encrypted sample.
  • https://localhost/shaka/?dash;vp9
    • Selects the VP9 sample and auto-plays it.
  • https://localhost/shaka/?dash;lang=fr
    • Sets the language to French and auto-plays.
  • https://localhost/shaka/?compiled;dash
    • Auto-plays the default sample in compiled mode.

The Loader

The Shaka Player library can be used without compiling it. This is useful when making changes, since it shortens the testing cycle for the developer. But the library will be deployed in a compiled form, so it is critical to test a change using the compiled library once it has been vetted uncompiled.

To make it easier to switch between compiled and uncompiled mode during testing and development, load.js acts as a shim between index.html and the library. It will select which version of the library to load based on the boolean parameter "compiled". (See "Test App" above for info on parameters.)

At any time during development or testing, you can switch modes by changing the URL. Once the application has loaded, you cannot change modes without reloading the page. A production application would directly include the compiled library instead of using this loader.

Remember, when running in compiled mode, you must recompile the library after a change by running ./build/all.sh.

Tests

Tests live in the "spec" folder and are run by unit_tests.html and integration_tests.html. To run tests, just point your browser at one of these HTML files. Do not do this using a file:// URL, but through a local web server.

You can also use karma to run the tests. These node packages are recommended to use karma:

  • karma
  • karma-jasmine
  • karma-jasmine-ajax
  • karma-chrome-launcher
  • jasmine
  • jasmine-ajax
  • jasmine-core
Then run: karma start --single-run --browsers Chrome

Source Code Layout

  • assets/ - assets for smoke-testing basic functionality
  • build/ - build scripts
    • build.sh - compiles the library and generates shaka-player.compiled.js
    • gendeps.sh - computes dependencies for running non-compiled code
    • lint.sh - checks the code for style issues
    • all.sh - combination of gendeps.sh, build.sh, and lint.sh
    • docs.sh - generate documentation
  • docs/ - documentation
    • api/ - generated documentation
    • reference/ - reference documents
  • externs/ - definitions of external APIs, used by the compiler
  • lib/ - the Shaka Player Library source, organized by namespace
    • dash/ - DASH-related classes (internal)
    • debug/ - debug-related classes (internal)
    • media/ - generic media-related and MSE-related classes (internal)
    • player/ - all classes that an integrator must interact with
    • polyfill/ - all Polyfills
    • util/ - utility classes (internal)
  • spec/ - unit and integration tests
  • spec_runner.html - front-end to run unit and integration tests
  • support.html - browser API support test
  • third_party/ - third_party dependencies
    • SUMMARY.txt - summary of all libraries and their licenses
    • blanket_jasmine/ - Blanket JS coverage library
    • closure/ - Closure JS compiler and JS library
    • jasmine/ - Jasmine JS testing framework
    • jsdoc/ - JS documentation generator
  • tutorials/ - source code for these tutorials

  • app.js - manual testing/sample application (JS)
  • index.html - manual testing/sample application (HTML)
  • index.css - manual testing/sample application (CSS)
  • load.js - library loader (for testing/bootstrapping)

  • jsdoc.conf.json - configuration for generating documentation
  • shaka-player.compiled.js - compiler output (suitable for deployment)
  • shaka-player.compiled.debug.js - compiler output (with debugging enabled via source map)
  • shaka-player.compiled.debug.map - compiler output (source map)
  • shaka-player.uncompiled.js - requires all exported classes in uncompiled mode