To get started quickly, just run ./build/all.sh and skip this document.
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".
The Shaka Player library was designed to be compiled with Google's open-sourced JavaScript compiler, {@link http://goo.gl/HZfHi 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 {@link http://usejsdoc.org/ 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 {@link http://goo.gl/xxHG2W 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 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.
Example URLs for the test app:
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 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: