Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 163 lines (113 sloc) 7.019 kb
9abdae1 Initial commit to enigmamachine.
dave authored
1 = enigmamachine
2
89fc908 Added a security warning and improved install docs.
dave authored
3 == Don't use this gem yet. The Enigmamachine wants to run on 0.0.0.0 rather than 127.0.0.1 (loopback) so you are opening a huge security hole on your server if you run this gem. Don't use it until this note goes away (real soon now). You have been warned.
4
f534fd2 A little status info.
dave@boomer authored
5 Enigmamachine is a video processor which queues and encodes videos according
6 to target profiles that you define. Videos must be on a locally mounted
7 filesystem. The processor takes the path to the video, and executes
24110ad Updated the README to reflect current project status.
dave authored
8 one or more ffmpeg commands on the video. There is a handy web interface for
f534fd2 A little status info.
dave@boomer authored
9 defining encoding tasks, and a restful web service which takes encoding commands.
10
11 Enigmamachine is written using Sinatra, Thin, and Eventmachine.
12
24110ad Updated the README to reflect current project status.
dave authored
13 == Why would you want one?
f534fd2 A little status info.
dave@boomer authored
14
24110ad Updated the README to reflect current project status.
dave authored
15 If you're not running a server, you probably don't need enigmamachine, because
16 there are already lots of great client-side batch processors for all kinds of
17 different operating systems. However, if you are running a web application,
18 and you want to process uploaded video, enigmamachine offers you a convenient
19 fire-and-forget video encoder.
20
21 The main problem with encoding video on a server is that it takes a really,
22 really long time - you don't want to do it within the scope of a single HTTP
23 request, because you want the user's browser to return to their control as
24 soon as the upload is finished. If the video took ten minutes to upload,
25 you don't want to keep their browser (and your webapp) busy for a
26 further ten minutes while the encoding happens.
27
28 The right way to deal with the uploaded video is to fire up a new thread which
29 can take over responsibility for encoding the video, while your web app goes
30 on its merry way. Unfortunately, this is difficult in some languages (PHP, for
31 example, doesn't have lightweight threading support), and even in languages
32 with good threading support it still sort of sucks. With Enigmamachine, all you
33 need to do to trigger encoding of a video is shoot off an HTTP request, and
34 everything else is handled for you.
35
36 == Using it
37
38 Once you've installed the gem (see below), you can do something like:
39
ff2f07d README formatting.
dave authored
40 mkdir enigma
41 cd enigma
42 enigmamachine start # -d to daemonize
24110ad Updated the README to reflect current project status.
dave authored
43
44 Then check it out in your browser, at http://localhost:2002.
45
46 Your application receives a video, and you do an HTTP call like:
47
48 POST http://localhost:2002/videos
49
50 with the params:
51
52 params["video"] # the full path to a file on your local filesystem
53 params["encoder_id"] # the id of an encoder defined in your database
54
55 The enigmamachine will run all encoding tasks on the video. If a new video is
56 uploaded while the first one is still encoding, it will be placed in a queue.
57 Videos are encoded sequentially as they arrive.
58
59 == Encoders and Encoding Tasks
60
19dfbf3 Some docs on the whole Encoders and Encoding Tasks thing.
dave authored
61 When you POST the location of a video to your enigmamachine, you need to tell
62 your EM what you want to do to the video. For example, you might want to take
63 an uploaded video and encode it as a 320x240 FLV video, with a 320x240 JPEG
64 thumbnail, and a 160x120 miniature thumbnail.
65
66 To do this, you'd fire up your enigmamachine by typing
67
68 enigmamachine start
69
70 and go to http://localhost:2002/encoders. Clicking the "new encoder" link will
71 allow you to define a new encoder. Let's call it "Flash video with a couple
72 thumbnails", and save it.
73
74 So, now there's an encoder, but it won't do anything. Let's add some tasks,
75 by clicking on the "new task" link.
76
77 Give the first task a name, like _Encode a 320x240 flv at 25 frames per second_.
78
79 The output file suffix in this case will be *.flv*.
80
81 The encoding command you'll want to use would be
82 _-ab 128 -ar 22050 -b 500000 -r 25 -s 320x240_. This cryptic command string
83 tells ffmpeg to encode a Flash video at 320x240 pixels, with an audio bitrate
84 of 128kbps, an audio sample rate of 22.050khz, and a frame rate of 25fps. You
85 can find out what all the ffmpeg command line switches do by RTFMing at
86 http://www.ffmpeg.org/ffmpeg-doc.html
87
88 You would go on to define a couple more encoding tasks for your encoder.
89 Grabbing a screen frame in ffmpeg can be done with the following command-line
90 switches, which you can put into a task called, let's say,
91 _Grab a 320x240 JPEG thumbnail_:
92
93 -ss 00:00:05 -t 00:00:01 -vcodec mjpeg -vframes 1 -an -f rawvideo -s 320x240
94
95 Rinse and repeat for the 160x120 thumbnail.
96
97 == Security
24110ad Updated the README to reflect current project status.
dave authored
98
414ce71 Further security warning.
dave authored
99 Enigmamachine should be set to bind by default to 127.0.0.1 (your system's loopback)
100 interface. However, the Thin webserver in the rackup file is currently making
101 itself available at IP 0.0.0.0, meaning it'll be available on all network
102 interfaces (unless you're running a firewall).
103
104 Making an enigmamachine available on an untrusted network (like
4aba731 A note on security.
dave authored
105 the Internet) would be a suicidal move on your part, since the code used to
106 talk to ffmpeg is a simple exec call and you'll be inviting everyone to
107 execute commands on your server.
108
109 If you don't know what any of this means, don't run it. I'm not responsible if
110 your enigmamachine screws up your system, allows people to exploit you, or
414ce71 Further security warning.
dave authored
111 eats your mother. I'm working on the security and will have updates ready soon.
112
24110ad Updated the README to reflect current project status.
dave authored
113
114 == Installation
115
116 Enigmamachine is written in Ruby and uses the Sinatra web framework, the
117 Datamapper ORM library, and the Eventmachine event-processing library. If
118 you're not a Ruby person, you don't need to care about any of this.
119 Enigmamachine can be triggered by any language that can send a POST request -
120 so all you PHPistas, python-lovers, droopy-moustachists, or blue-suited
121 java types can all use it just as easy as us fashionable-haircut-language
122 people.
123
124 You can install it as a gem by doing:
125
126 gem install enigmamachine
127
128 If this command doesn't make any sense to you, it's because you don't know that
129 "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
130 You can install rubygems, necessary sqlite headers, and a C compiler on
131 righteous operating systems by typing:
24110ad Updated the README to reflect current project status.
dave authored
132
ea62e23 Added a couple of extra apt package dependencies.
dave authored
133 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
134
b0f92d9 More docs fixes.
dave authored
135 Then _gem install enigmamachine_ should theoretically work. You'll also need a copy of
469b5d5 More docs love.
dave authored
136 ffmpeg installed and available in your path. On Mac OS X, rubygems should
137 already be installed, although you'll need to have a C compiler available
138 (make sure you install the developer tools that came with your operating
139 system).
24110ad Updated the README to reflect current project status.
dave authored
140
141 == Status
142
143 This thing is still pre-release.
144
145 I'm just working on getting the gem dependencies correct, so you may need to
146 manually install a few things to get it to work. You'll also need a working
147 copy of ffmpeg available on your path.
f534fd2 A little status info.
dave@boomer authored
148
9abdae1 Initial commit to enigmamachine.
dave authored
149
150 == Note on Patches/Pull Requests
15101c3 Initial commit.
dave authored
151
9abdae1 Initial commit to enigmamachine.
dave authored
152 * Fork the project.
153 * Make your feature addition or bug fix.
154 * Add tests for it. This is important so I don't break it in a
155 future version unintentionally.
15101c3 Initial commit.
dave authored
156 * 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
157 * Send me a pull request. Bonus points for topic branches.
158
159 == Copyright
160
15101c3 Initial commit.
dave authored
161 Copyright (c) 2010 Dave Hrycyszyn. See LICENSE for details.
162
Something went wrong with that request. Please try again.