Skip to content
Newer
Older
100644 211 lines (132 sloc) 7.28 KB
4a4622f @pdeschen rename to markdown extension + some markdown formatting on headers + …
pdeschen authored Mar 31, 2012
1
e08a666 @pkrumins node-video now takes only RGB buffers (no longer RGBA)
authored Jul 12, 2010
2 This is a node.js module, writen in C++, that produces Theora/Ogg videos from
3 the given RGB buffers.
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
4
5 It was written by Peteris Krumins (peter@catonmat.net).
6 His blog is at http://www.catonmat.net -- good coders code, great reuse.
7
8 ------------------------------------------------------------------------------
9
10 This module exports several objects that you can work with:
11
12 * FixedVideo - to create videos from fixed size frames
88c7bbe @pkrumins StackedVideo is now implemented
authored Jun 30, 2010
13 * StackedVideo - to create videos from fragmented frames (stack them together)
1dfbc74 @pkrumins readme.txt now reflects AsyncStackedVideo
authored Aug 19, 2010
14 * AsyncStackedVideo - same as StackedVideo but asynchronous
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
15
16 // these are not there yet, still hacking them in right now.
17 // * StreamingVideo - to create streamable videos (works with HTML5 <video>)
18
4a4622f @pdeschen rename to markdown extension + some markdown formatting on headers + …
pdeschen authored Mar 31, 2012
19 ##FixedVideo
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
20
21 FixedVideo object is for creating videos from fixed size frames. That is,
22 each frame is exactly the same size, for example, each frame is 720x400 pixels.
23
24 Here is how to use FixedVideo. First you need to create a new instance of this
25 object. The constructor takes two arguments `width` and `height` of the video:
26
27 var video = new FixedVideo(width, height);
28
29 Next, you need to set the output file this video will be written to. This is
30 done via `setOutputFile` method, it can be relative or absolute path. If nodejs
31 doesn't have the necessary permissions to write the file, it will throw an
32 exception as soon as you submit the first frame. Here is how you use setOutputFile:
33
34 video.setOutputFile('./cool_video.ogv');
35
36 The .ogv extension stands for ogg-video.
37
38 Then you can also change the quality of the video via `setQuality` method. The
39 quality must be between 0-63, where 0 is the worst quality and 63 is the best.
40 The default quality is 31.
41
42 video.setQuality(63); // best video quality
43
a2d0497 @pkrumins added setFrameRate
authored Jun 29, 2010
44 You can also change the frame rate with `setFrameRate`. The default is 25fps,
45 to change it do this:
46
47 video.setFrameRate(50); // frame rate is now 50 fps
48
e7d482f @pkrumins added setKeyFrameInterval method to control keyframe interval
authored Jul 7, 2010
49 The keyframe interval can also be controlled. Use `setKeyFrameInterval` to set it.
50 It must be a power of two:
51
52 video.setKeyFrameInterval(128); // keyframe every 128 frames
53
a2d0497 @pkrumins added setFrameRate
authored Jun 28, 2010
54 Important: All of the above options should be set before submitting the first
55 frame.
56
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
57 Now, to start writing video, call `newFrame` method with frames sequentially.
e08a666 @pkrumins node-video now takes only RGB buffers (no longer RGBA)
authored Jul 12, 2010
58 Frames must be RGB nodejs Buffer objects.
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
59
e08a666 @pkrumins node-video now takes only RGB buffers (no longer RGBA)
authored Jul 12, 2010
60 video.newFrame(rgb_frame);
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
61
62 FixedVideo is lazy by itself and will write headers of the video only after
63 receiving the first frame, so the first frame may take longer to encode than
64 subsequent, because there is a lot of initialization going on.
65
66 If at any time you're done writing video, call the `end` method,
67
68 video.end();
69
70 This will close all open files and free resources. But you can also leave it
71 to garbage collector. If `video` goes out of scope, it also closes the video
72 file and frees all resources.
73
74
4a4622f @pdeschen rename to markdown extension + some markdown formatting on headers + …
pdeschen authored Mar 31, 2012
75 ##StackedVideo
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
76
df9c255 @pkrumins added StackedVideo description
authored Jun 30, 2010
77 StackedVideo object is for stacking many small frame updates together and then
78 encoding the frame as a whole. Here is how it works. The first frame sent to
79 StackedVideo must be a full frame (the width and height must match video's
80 width and height). Next, you can either send another full frame for encoding
81 or update parts of the last frame. It's useful in a situation like doing a
82 screen recording, when only one smart part of the screen updates, you redraw
83 just that portion and nothing else.
84
85 Must of the usage is just like you'd use FixedVideo object.
86
87 First create a StackedVideo object:
88
89 var stackedVideo = new StackedVideo(width, height);
90
91 Then set the output file:
92
93 stackedVideo.setOutputFile('./screencast.ogv');
94
e7d482f @pkrumins added setKeyFrameInterval method to control keyframe interval
authored Jul 7, 2010
95 Then set the quality, framerate, keyframe interval, via `setQuality`,
96 `setFrameRate`, `setKeyFrameInterval` methods.
df9c255 @pkrumins added StackedVideo description
authored Jun 30, 2010
97
98 Now you have to submit a full frame to StackedVideo, do it via regular
99 `newFrame` method:
100
e08a666 @pkrumins node-video now takes only RGB buffers (no longer RGBA)
authored Jul 12, 2010
101 stackedVideo.newFrame(rgb_frame);
df9c255 @pkrumins added StackedVideo description
authored Jun 30, 2010
102
103 This will encode this frame, and remember it. Now you can use `push` method
104 to push an update to the frame. The usage is as following:
105
e08a666 @pkrumins node-video now takes only RGB buffers (no longer RGBA)
authored Jul 12, 2010
106 stackedVideo.push(rgb_rectangle, x, y, width, height);
df9c255 @pkrumins added StackedVideo description
authored Jun 30, 2010
107
108 This will put the rectangle of width x height at position (x, y). Make sure
1f7bc94 @pkrumins can use push() as well instead of newFrame for the first frame
authored Jul 5, 2010
109 dimensions don't overflow or you'll get an exception. You can also push the
110 first full frame with this method instead of using newFrame, make sure that
111 (x,y) = (0,0) and width, height are video's width, height.
df9c255 @pkrumins added StackedVideo description
authored Jun 30, 2010
112
113 After you're done pushing all the updates you wanted, call `endPush`. This
114 will encode the frame (and keep the previous frame in memory, so you can `push`
115 more stuff):
116
117 stackedVideo.endPush();
118
e08a666 @pkrumins node-video now takes only RGB buffers (no longer RGBA)
authored Jul 12, 2010
119 Stacked videos can also duplicate previous frames cheaply to imitate VFR (variable
120 frame rate). Pass millisecond argument to `endPush` to make it duplicate the previous
121 for the right amount of time. Here is what I mean,
122
123 If you call,
124
125 stackedVideo.endPush((new Date).getTime());
126
127 every time, then the previous frame will be duplicated the right number of times
128 so that video played at the right framerate.
129
df9c255 @pkrumins added StackedVideo description
authored Jun 30, 2010
130 When you're totally done with encoding, call the `end` method:
131
132 stackedVideo.end();
133
134 That will close all the file handles and free memory. Alternatively you can let
135 the `stackedVideo` object go out of scope, which will have the same effect.
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
136
137
4a4622f @pdeschen rename to markdown extension + some markdown formatting on headers + …
pdeschen authored Mar 31, 2012
138 ##AsyncStackedVideo
1dfbc74 @pkrumins readme.txt now reflects AsyncStackedVideo
authored Aug 19, 2010
139
140 AsyncStackedVideo is the same as StackedVideo except it's asynchronous.
141
142 var asyncVideo = new AsyncStackedVideo(width, height);
143 asyncVideo.setOutputFile('./video.ogv');
144
145 To use it you must specify the temporary directory for fragments (it writes them
146 asynchronously to disk):
147
148 asyncVideo.setTmpDir('/tmp/foo');
149
150 Next you .push fragments to it, and after you're done with one frame,
151 you call .endPush.
152
153 Then when you're totally done with all the frames, call .encode and pass it a
154 callback function, which will be called once the encoding is done:
155
156 asyncVideo.encode(function (ok, error) {
157 if (ok) {
158 // video was written to the file you set by .setOutputFile
159 }
160 else {
161 // failure, examine 'error'
162 }
163 });
164
165
4a4622f @pdeschen rename to markdown extension + some markdown formatting on headers + …
pdeschen authored Mar 31, 2012
166 ##StreamingVideo
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
167
168 Also coming near you soon. This is the most awesome stuff!
169
170
4a4622f @pdeschen rename to markdown extension + some markdown formatting on headers + …
pdeschen authored Mar 31, 2012
171 ##How to compile?
56e5266 @pkrumins added 'how to compile?' to readme
authored Jul 1, 2010
172
173 You need node.js installed to compile this module. When installed it comes with
174 node-waf tool, run it in this libs dir:
175
176 node-waf configure build
177
178 This will produce video.node dll. After that, make sure NODE_PATH contains lib's
179 dir.
180
4a4622f @pdeschen rename to markdown extension + some markdown formatting on headers + …
pdeschen authored Mar 31, 2012
181 ## Installation
56e5266 @pkrumins added 'how to compile?' to readme
authored Jul 1, 2010
182
4a4622f @pdeschen rename to markdown extension + some markdown formatting on headers + …
pdeschen authored Mar 31, 2012
183 npm install node-video [-g]
184
185 ##Other stuff in this module
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
186
187 The discovery/ directory contains all the snippets I wrote to understand how
188 to get video working. It's a habit of effective hackers to try lots of small
189 things out until you get the whole picture of how things should work. I call
190 it "the hacker's approach," where you hack stuff up quickly without any
191 understanding, and then rewrite it to produce working modules.
192
193 I also tried libx264 but since it was only supported by Chrome, I went with
194 libtheora. Maybe I'll add libx264 later as it gets support from more browsers.
195
1f7bc94 @pkrumins can use push() as well instead of newFrame for the first frame
authored Jul 4, 2010
196 This library was written for my and SubStack's StackVM startup.
199e3b9 @pkrumins finally done with readme for FixedVideo, Stacked and Streaming videos…
authored Jun 28, 2010
197
198 ------------------------------------------------------------------------------
199
200 Happy videoing!
201
202
203 Sincerely,
204 Peteris Krumins
205 http://www.catonmat.net
206
4a4622f @pdeschen rename to markdown extension + some markdown formatting on headers + …
pdeschen authored Mar 31, 2012
207 ## Contributors
208
209 * Node v0.3 buffers (James Halliday substack)
210 * Node v0.6 compatibility (Pascal Deschenes <pdeschen at gmail dot com>)
Something went wrong with that request. Please try again.