Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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