/README.markdown

  1Broadway.js
  2===========
  3A JavaScript H.264 decoder.
  4
  5
  6View a Live Demo:  
  7http://mbebenita.github.io/Broadway/foxDemo.html  
  8http://mbebenita.github.io/Broadway/storyDemo.html  
  9http://mbebenita.github.io/Broadway/treeDemo.html  
 10
 11The video player first needs to download the entire video before it can start playing, thus appearing to be a bit slow at first, so have patience. You can start the video by clicking on each player. The top left player runs on the main thread, the remaining players run in background worker threads.
 12
 13Use a example node app as template:  
 14https://github.com/soliton4/BroadwayStream  
 15
 16Technical info
 17==============
 18
 19The demo is Android's H.264 decoder compiled with Emscripten to JavaScript, then further optimized with
 20Google's JavaScript closure compiler and further optimized by hand to use WebGL.
 21
 22Building the demo:
 23
 24Install and configure Emscripten (https://github.com/kripken/emscripten)  
 25The current version of Broadway was built with emscripten 1.35.12  
 26
 27The code for the demo is in the Decoder folder, to build it run the make.py python script. (Requires at least python 2.7)
 28
 29Encoding Video
 30==============
 31
 32The decoder expects an .mp4 file and does not support weighted prediction for P-frames and CABAC entropy encoding. To create such bitstreams use ffmpeg and x264 with the following command line options:
 33
 34```
 35ffmpeg -y -i sourceFile -r 30000/1001 -b:a 2M -bt 4M -vcodec libx264 -pass 1 -coder 0 -bf 0 -flags -loop -wpredp 0 -an targetFile.mp4
 36```
 37
 38API
 39===
 40
 41Player.js, Decoder.js and YUVWebGLCanvas.js all have a unified module definition.  
 42You can use them as plain js files or with common.js / AMD  
 43
 44# Player.js:  
 45
 46```
 47var p = new Player({
 48  <options>
 49});
 50
 51p.canvas; // the canvas - put it where you want it
 52
 53p.decode(<h264 data>);
 54```
 55
 56## options:  
 57
 58useWorker true / false  
 59decode in a worker thread  
 60
 61workerFile <string>  
 62path to Decoder.js. Only neccessary when using worker. defaults to "Decoder.js"  
 63
 64webgl true / "auto" / false  
 65use webgl. defaults to "auto"  
 66
 67size { width: <num>, height: <num> }  
 68initial size of the canvas. canvas will resize after video starts streaming.  
 69
 70## properties:  
 71
 72canvas  
 73domNode  
 74
 75refers to the canvas element.  
 76
 77## methods:  
 78
 79decode (<bin>)
 80
 81feed the decoder with h264 stream data.  
 82
 83
 84# Decoder.js:  
 85
 86```
 87var p = new Decoder({
 88  <options>
 89});
 90
 91p.onPictureDecoded; // override with a callback function
 92
 93p.decode(<h264 data>);
 94```
 95
 96## options:  
 97
 98rgb true / false  
 99if true will convert the image to rgb. sligtly slower.  
100
101## properties:  
102
103onPictureDecoded  callback function(<bin>, width, height)
104
105will be called for each frame.
106
107## methods:  
108
109decode (<bin>)
110
111feed the decoder with h264 stream data.  
112
113
114# [Real World Uses of Broadway.js](https://github.com/mbebenita/Broadway/wiki/Real-World-Uses)