Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 228 lines (159 sloc) 9.127 kB
9abdae1 Initial commit to enigmamachine.
dave authored
1 = enigmamachine
2
89b550c Updated the HTTP basic auth part of the README so it's correct.
dave authored
3 Enigmamachine is a RESTful web-based video processor which queues and encodes
4 videos according to target profiles that you define. Videos must be on a
5 locally mounted filesystem. The processor takes the path to the video, and
6 executes one or more ffmpeg commands on the video. There is a handy web
7 interface for defining encoding tasks, and a restful web service which takes
8 encoding commands.
f534fd2 A little status info.
dave@boomer authored
9
10 Enigmamachine is written using Sinatra, Thin, and Eventmachine.
11
24110ad Updated the README to reflect current project status.
dave authored
12 == Why would you want one?
f534fd2 A little status info.
dave@boomer authored
13
24110ad Updated the README to reflect current project status.
dave authored
14 If you're not running a server, you probably don't need enigmamachine, because
15 there are already lots of great client-side batch processors for all kinds of
16 different operating systems. However, if you are running a web application,
17 and you want to process uploaded video, enigmamachine offers you a convenient
18 fire-and-forget video encoder.
19
20 The main problem with encoding video on a server is that it takes a really,
21 really long time - you don't want to do it within the scope of a single HTTP
22 request, because you want the user's browser to return to their control as
23 soon as the upload is finished. If the video took ten minutes to upload,
24 you don't want to keep their browser (and your webapp) busy for a
25 further ten minutes while the encoding happens.
26
27 The right way to deal with the uploaded video is to fire up a new thread which
28 can take over responsibility for encoding the video, while your web app goes
29 on its merry way. Unfortunately, this is difficult in some languages (PHP, for
30 example, doesn't have lightweight threading support), and even in languages
31 with good threading support it still sort of sucks. With Enigmamachine, all you
32 need to do to trigger encoding of a video is shoot off an HTTP request, and
33 everything else is handled for you.
34
35 == Using it
36
37 Once you've installed the gem (see below), you can do something like:
38
ff2f07d README formatting.
dave authored
39 mkdir enigma
40 cd enigma
41 enigmamachine start # -d to daemonize
24110ad Updated the README to reflect current project status.
dave authored
42
01ab309 Some slightly improved usage docs.
dave authored
43 Then check it out in your browser, at http://localhost:2002. This web interface
44 exists so that you can configure your enigmamachine easily, and check its status.
24110ad Updated the README to reflect current project status.
dave authored
45
01ab309 Some slightly improved usage docs.
dave authored
46 Most of the time, though, your enigmamachine will be accessed not through a
372755a Minor docs changes.
dave authored
47 browser, but by your program's code. Let's say you want your website to be able to
01ab309 Some slightly improved usage docs.
dave authored
48 enocode video. You write the code for the video upload, so your web app can
bdf0ee5 More docs love.
dave authored
49 receive the video. When the upload is complete, make an HTTP call something like this in your code:
24110ad Updated the README to reflect current project status.
dave authored
50
51 POST http://localhost:2002/videos
52
53 with the params:
54
89b550c Updated the HTTP basic auth part of the README so it's correct.
dave authored
55 "video=/foo/bar/blah.mp4" # the full path to a file on your local filesystem
56 "encoder_id=1" # the id of an encoder defined in your enigmamachine database
24110ad Updated the README to reflect current project status.
dave authored
57
89b550c Updated the HTTP basic auth part of the README so it's correct.
dave authored
58 The enigmamachine will run all encoding tasks on the video, while your web
59 application will be free to continue serving requests happily. If a second video
bdf0ee5 More docs love.
dave authored
60 is uploaded while the first one is still encoding, it will be placed in a queue.
24110ad Updated the README to reflect current project status.
dave authored
61 Videos are encoded sequentially as they arrive.
62
21ee22e Updated usage docs with a sample ruby client.
dave authored
63 All requests, whether they come from your browser or from your code, are
64 protected by HTTP basic auth. By default, the username is
6713b7a Put in a note about config.yml.
dave authored
65 <i>admin</i> and the password is <i>admin</i>. You can change the username and
66 password in the config.yml file which will be generated on first use.
21ee22e Updated usage docs with a sample ruby client.
dave authored
67
68 Programmatic requests in Ruby might look something like this:
69
697f66d An actually working enigma_client.rb.
dave authored
70 # enigma_client.rb:
71
21ee22e Updated usage docs with a sample ruby client.
dave authored
72 require 'rubygems'
91f8293 The damned client really works now. Really!
dave authored
73 require 'httparty'
21ee22e Updated usage docs with a sample ruby client.
dave authored
74
75 class EnigmaClient
76
91f8293 The damned client really works now. Really!
dave authored
77 include HTTParty
78
79 base_uri "localhost:2002"
80
21ee22e Updated usage docs with a sample ruby client.
dave authored
81 def initialize (u, p)
91f8293 The damned client really works now. Really!
dave authored
82 @auth = encode_credentials(u, p)
21ee22e Updated usage docs with a sample ruby client.
dave authored
83 end
84
85 def post(path_to_video, encoder_id)
91f8293 The damned client really works now. Really!
dave authored
86 self.class.post("/videos", {
87 :body => {:video => {:file => path_to_video}, :encoder_id => encoder_id},
88 :basic_auth => @auth})
89 end
90
91 private
92
93 def encode_credentials(username, password)
94 {:username => username, :password => password}
21ee22e Updated usage docs with a sample ruby client.
dave authored
95 end
96
97 end
98
91f8293 The damned client really works now. Really!
dave authored
99
21ee22e Updated usage docs with a sample ruby client.
dave authored
100 # Let's use it!
101 #
697f66d An actually working enigma_client.rb.
dave authored
102 irb
103 require 'enigma_client'
21ee22e Updated usage docs with a sample ruby client.
dave authored
104 EnigmaClient.new("admin", "admin").post("/path/to/your/uploaded/video.mp4", 1)
105
106
313bf0e Added a working wget example to the invocation docs.
dave authored
107 A simpler, wget-based approach might look like this:
108
109 wget http://admin:admin@localhost:2002/videos --post-data 'video[file]=/path/to/your/video.mp4&encoder_id=1'
110
111 <b>Don't use wget like this on a shared host, it's insecure</b> (read the wget
112 docs for more on this). This wget example is just to show you what's going on
113 when using a simple tool that most programmers know how to use.
114
24110ad Updated the README to reflect current project status.
dave authored
115 == Encoders and Encoding Tasks
116
19dfbf3 Some docs on the whole Encoders and Encoding Tasks thing.
dave authored
117 When you POST the location of a video to your enigmamachine, you need to tell
118 your EM what you want to do to the video. For example, you might want to take
119 an uploaded video and encode it as a 320x240 FLV video, with a 320x240 JPEG
120 thumbnail, and a 160x120 miniature thumbnail.
121
122 To do this, you'd fire up your enigmamachine by typing
123
124 enigmamachine start
125
126 and go to http://localhost:2002/encoders. Clicking the "new encoder" link will
127 allow you to define a new encoder. Let's call it "Flash video with a couple
128 thumbnails", and save it.
129
130 So, now there's an encoder, but it won't do anything. Let's add some tasks,
131 by clicking on the "new task" link.
132
e069237 README formatting fixes.
dave authored
133 Give the first task a name, like <i>Encode a 320x240 flv at 25 frames per second</i>.
19dfbf3 Some docs on the whole Encoders and Encoding Tasks thing.
dave authored
134
135 The output file suffix in this case will be *.flv*.
136
137 The encoding command you'll want to use would be
e069237 README formatting fixes.
dave authored
138 <i>-ab 128 -ar 22050 -b 500000 -r 25 -s 320x240</i>. This cryptic command string
19dfbf3 Some docs on the whole Encoders and Encoding Tasks thing.
dave authored
139 tells ffmpeg to encode a Flash video at 320x240 pixels, with an audio bitrate
140 of 128kbps, an audio sample rate of 22.050khz, and a frame rate of 25fps. You
141 can find out what all the ffmpeg command line switches do by RTFMing at
142 http://www.ffmpeg.org/ffmpeg-doc.html
143
144 You would go on to define a couple more encoding tasks for your encoder.
145 Grabbing a screen frame in ffmpeg can be done with the following command-line
146 switches, which you can put into a task called, let's say,
e069237 README formatting fixes.
dave authored
147 <i>Grab a 320x240 JPEG thumbnail</i>:
19dfbf3 Some docs on the whole Encoders and Encoding Tasks thing.
dave authored
148
149 -ss 00:00:05 -t 00:00:01 -vcodec mjpeg -vframes 1 -an -f rawvideo -s 320x240
150
151 Rinse and repeat for the 160x120 thumbnail.
152
21ee22e Updated usage docs with a sample ruby client.
dave authored
153 == Security considerations
24110ad Updated the README to reflect current project status.
dave authored
154
a00ed9b Removed security warnings, the app now listens on loopback only.
dave authored
155 Enigmamachine is set to bind by default to 127.0.0.1 (your system's loopback)
21ee22e Updated usage docs with a sample ruby client.
dave authored
156 interface rather than on all network interfaces, so it won't be accessible from
157 other machines.
414ce71 Further security warning.
dave authored
158
159 Making an enigmamachine available on an untrusted network (like
4aba731 A note on security.
dave authored
160 the Internet) would be a suicidal move on your part, since the code used to
0a63378 Some updated security docs.
dave authored
161 talk to ffmpeg is a simple backtick exec call and you'll be inviting everyone in
162 the world to execute commands on your server, with your effective user
163 permissions.
164
165 When the enigmamachine starts for the first time in a given directory, it will
166 spit out a config.yml file containing a username and password. All requests
167 will need to submit this auth information. This should make enigmamachine
21ee22e Updated usage docs with a sample ruby client.
dave authored
168 reasonably safe to use on shared hosts, just make sure nobody can read the
169 config file except the user executing the enigmamachine process.
4aba731 A note on security.
dave authored
170
171 If you don't know what any of this means, don't run it. I'm not responsible if
172 your enigmamachine screws up your system, allows people to exploit you, or
a00ed9b Removed security warnings, the app now listens on loopback only.
dave authored
173 eats your mother.
24110ad Updated the README to reflect current project status.
dave authored
174
175 == Installation
176
177 Enigmamachine is written in Ruby and uses the Sinatra web framework, the
5bf8bdb Minor docs changes, let's not forget about Thin.
dave authored
178 Datamapper ORM library, the Eventmachine event-processing library, and the Thin
179 webserver. If you're not a Ruby person, you don't need to care about any of this.
24110ad Updated the README to reflect current project status.
dave authored
180 Enigmamachine can be triggered by any language that can send a POST request -
181 so all you PHPistas, python-lovers, droopy-moustachists, or blue-suited
182 java types can all use it just as easy as us fashionable-haircut-language
183 people.
184
185 You can install it as a gem by doing:
186
187 gem install enigmamachine
188
189 If this command doesn't make any sense to you, it's because you don't know that
190 "gems" are ruby code packages, somewhat like apt-get except for ruby code only.
89fc908 Added a security warning and improved install docs.
dave authored
191 You can install rubygems, necessary sqlite headers, and a C compiler on
192 righteous operating systems by typing:
24110ad Updated the README to reflect current project status.
dave authored
193
f96f69e Added ffmpeg to the list of packages which need to be installed.
dave authored
194 apt-get install rubygems ruby1.8-dev libopenssl-ruby build-essential libsqlite3-dev ffmpeg # as root
24110ad Updated the README to reflect current project status.
dave authored
195
9eb8658 Added PATH export stuff for .bashrc into place.
dave authored
196 You'll need to add the following line to your ~/.bashrc file, as well:
197
198 export PATH=/var/lib/gems/1.8/bin:$PATH
199
5bf8bdb Minor docs changes, let's not forget about Thin.
dave authored
200 Then <i>gem install enigmamachine</i> should theoretically work. You'll also need a copy of
469b5d5 More docs love.
dave authored
201 ffmpeg installed and available in your path. On Mac OS X, rubygems should
202 already be installed, although you'll need to have a C compiler available
203 (make sure you install the developer tools that came with your operating
204 system).
24110ad Updated the README to reflect current project status.
dave authored
205
206 == Status
207
208 This thing is still pre-release.
209
210 I'm just working on getting the gem dependencies correct, so you may need to
211 manually install a few things to get it to work. You'll also need a working
212 copy of ffmpeg available on your path.
f534fd2 A little status info.
dave@boomer authored
213
9abdae1 Initial commit to enigmamachine.
dave authored
214
215 == Note on Patches/Pull Requests
15101c3 Initial commit.
dave authored
216
9abdae1 Initial commit to enigmamachine.
dave authored
217 * Fork the project.
218 * Make your feature addition or bug fix.
219 * Add tests for it. This is important so I don't break it in a
220 future version unintentionally.
15101c3 Initial commit.
dave authored
221 * Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
9abdae1 Initial commit to enigmamachine.
dave authored
222 * Send me a pull request. Bonus points for topic branches.
223
224 == Copyright
225
15101c3 Initial commit.
dave authored
226 Copyright (c) 2010 Dave Hrycyszyn. See LICENSE for details.
227
Something went wrong with that request. Please try again.