Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

241 lines (156 sloc) 10.886 kB



Codem-transcode is an offline video transcoder written in node.js. It

  1. Uses ffmpeg for transcoding
  2. Has a simple HTTP API
  3. Is mostly asynchronous

Codem-transcode can be used in conjunction with Codem-schedule ( for robust job scheduling and notifications or it can be used stand-alone, with or without a custom scheduler.



The recommended installation procedure is to just use npm (

# npm install codem-transcode

Install it to your preferred location, or use the -g option to install it globally.


Upgrading should most of the times be as simple as shutting down, installing the new package and restarting the transcoder. Unless you're...

Upgrading from earlier versions to 0.5 (IMPORTANT!)

Codem-transcode switched from using "plain" SQL (using sqlite) to a database abstraction layer (Sequelize). This brings some advantages (support for multiple database engines, better consistency, easier migrations in the future), but is not backwards compatible. Therefore, we recommend you backup and move away your old database and start with a fresh one. The procedure for this would be:

  • Shutdown the transcoder;
  • Move your database away (or delete if you're not interested in the history);
  • Install the new package;
  • Start the transcoder.

This will initialize a new up-to-date database which can be migrated to newer schema's more easily in the future. If you are doing a clean install you do not need to worry about any of this.

If you want to keep your history we recommend you follow the above procedure and write a separate import script to import your old data into the new database.


When you install codem-transcode a script will be installed that allows you to start the transcoder. If you install it globally it should be in your PATH, otherwise, you can start the transcoder using:

# /PATH/TO/TRANSCODER/bin/codem-transcode

Please check for yourself where npm installs your packages and script.


Configuration is done by specifying a CLI option (-c) and pointing to a file containing a valid JSON object ( Note that node.js' JSON parser is fairly strict so make sure you get the syntax right. An example config is:

    "port":            8080,
    "access_log":      "/var/log/access_log",
    "database":        "/var/db/jobs.db",
    "slots":           8,
    "interface":       "",
    "encoder":         "ffmpeg",
    "scratch_dir":     "/tmp",
    "use_scratch_dir": true,
    "ffprobe":         null

Configuration options:

  • port; port to start server on, default 8080
  • interface; which network interface to listen on, default (only localhost)
  • access_log; location to store HTTP access log, default /var/log/access_log
  • database; location to store the jobs database, default is SQLite with /var/db/jobs.db
  • slots; number of transcoding slots to use (i.e. the maximum number of ffmpeg child processes), defaults to the number of CPUs/cores in your machine
  • encoder; path to the ffmpeg binary, if it is in your path specifying only ffmpeg is sufficient, defaults to ffmpeg
  • scratch_dir; temporary files are written here and moved into the destination directory after transcoding, defaults to /tmp
  • use_scratch_dir; if set to false temporary files will be written to the output directory of your job, for setups that don't require or are not able to use a separate scratch_dir. Defaults to true so if you don't want to disable the scratch_dir you can also omit this option from your config file.
  • ffprobe; path to the ffprobe binary, if it is in your path specifying only ffprobe is sufficient, defaults to null. Set this to a non-null value if you want to enable ffprobe support in the transcoder.

Note that the default config will put the access_log and job database in /var/log and var/db/ respectively. If you wish to put these in a different location please supply your own config. You can start the transcoder with your custom config using:

# /PATH/TO/TRANSCODER/bin/codem-transcode -c /PATH/TO/CONFIG/config.json

Advanced database configuration

codem-transcode supports multiple database backends, courtesy of Sequelize. The default is still to store data in a SQLite database (whenever you specify a string for database in the config file). To use MySQL or Postgres, supply a valid object for the database entry. Your configuration will then look like:

    "port":            8080,
    "access_log":      "/var/log/access_log",
    "database":        {
        "dialect": "mysql",
        "username": "root",        
        "database": "codem",
        "host": "localhost"
    "slots":           8,
    "interface":       "",
    "encoder":         "ffmpeg",
    "scratch_dir":     "/tmp",
    "use_scratch_dir": true,
    "ffprobe":         null

Be sure to specify a dialect ("mysql", "postgres", "sqlite"), a username, a password (can be omitted if using a passwordless database) and a host (can be omitted for "localhost").


After starting the server you can control it using most HTTP CLI tools, such as curl or wget. The HTTP API is as follows:

Request: POST /jobs

Parameters (HTTP POST data, should be valid JSON object):

    "source_file": "/PATH/TO/INPUT/FILE.wmv",
    "encoder_options": "-acodec libfaac -ab 96k -ar 44100 -vcodec libx264 -vb 416k -s 320x180 -y -threads 0",
    "callback_urls": [""]


  • 202 Accepted - Job accepted
  • 400 Bad Request - Invalid request (format)
  • 503 Service Unavailable - Transcoder not accepting jobs at the moment (all encoding slots are in use)

The callback_urls array is optional and is a list (array) of HTTP endpoints that should be notified once encoding finishes (due to the job being complete or some error condition). All other options are required (source_file, destination_file and encoder_options). Input and output files should be absolute paths.

Request: GET /jobs


  • 200 OK - Returns status of all active jobs

Request: GET /jobs/$JOB_ID


  • 200 OK - Returns status of job
  • 404 Not Found - Job not found

Request: DELETE /jobs/$JOB_ID

Cancels the job (if it is running) and deletes it from the database.


  • 200 OK - Returns last known status of the job that is being deleted
  • 404 Not Found - Job not found

Request: POST /probe

Probe a source file using ffprobe (if you have enabled it in the configuration). Output is a JSON object containing the ffprobe output.

Parameters (HTTP POST data, should be valid JSON object):

    "source_file": "/PATH/TO/INPUT/FILE.wmv"


  • 200 OK - Returns ffprobe output JSON-formatted
  • 400 Bad Request - Returned if you attempt to probe a file when there is no path set to the ffprobe binary
  • 500 Internal Server Error - Returned if there was an error while trying to probe, the output from ffprobe will be returned as well


Create a new job, transcode "video.wmv" to "video.mp4" using the specified ffmpeg options (96kbit/s audio, 416kbit/s video, 320x180, use as much threads as possible). Requires libx264 support in your ffmpeg.

# curl -d '{"source_file": "/tmp/video.wmv","destination_file":"/tmp/video.mp4","encoder_options": "-acodec libfaac -ab 96k -ar 44100 -vcodec libx264 -vb 416k -s 320x180 -y -threads 0"}' http://localhost:8080/jobs

Output: {"message":"The transcoder accepted your job.","job_id":"d4b1dfebe6860839b2c21b70f35938d870011682"}

Create a new job, transcode "video.mpg" to "video.webm" using the specified ffmpeg options (total bitrate 512kbit/s, 320x180, use as much threads as possible). Requires libvpx support in your ffmpeg.

# curl -d '{"source_file": "/tmp/video.mpg","destination_file":"/tmp/video.webm","encoder_options": "-vcodec libvpx -b 512000 -s 320x180 -acodec libvorbis -y -threads 0"}' http://localhost:8080/jobs

Output: {"message":"The transcoder accepted your job.","job_id":"c26769be0955339db8f98580c212b7611cacf4dd"}

Get status of all available encoder slots.

# curl http://localhost:8080/jobs

Output: {"max_slots":8,"free_slots":8,"jobs":[]}


Output: {"max_slots":8, "free_slots":7, "jobs":[{"id":"da56da6012bda2ce775fa028f056873bcb29cb3b", "status":"processing", "progress":0.12480252764612954, "duration":633, "filesize":39191346, "message":null}]}

Get full status of one job with id "da56da6012bda2ce775fa028f056873bcb29cb3b".

# curl http://localhost:8080/jobs/da56da6012bda2ce775fa028f056873bcb29cb3b

Output: {"id":"da56da6012bda2ce775fa028f056873bcb29cb3b", "status":"processing", "progress":0.21800947867298578, "duration":633, "filesize":39191346, "opts":"{\"source_file\":\"/shared/videos/asf/video.asf\", \"destination_file\":\"/shared/videos/mp4/journaal.mp4\", \"encoder_options\":\"-acodec libfaac -ab 96k -ar 44100 -vcodec libx264 -vb 416k -s 320x180 -y -threads 0\"}", "message":null, "created_at":1304338160, "updated_at":1304338173}

Probe a file using ffprobe.

# curl -d '{"source_file": "/tmp/video.wmv"}' http://localhost:8080/probe

Output: {"ffprobe":{"streams":[ ... stream info ... ],"format":{ ... format info ... }}}}



All tests are written using jasmine (via jasmine-node). Running them is as easy as:

# jasmine-node test

More specs coming soon.

Issues and support

If you run into any issues while using codem-transcode please use the Github issue tracker to see if it is a known problem or report it as a new one.

We also provide commercial support for codem-transcode (for bugs, features, configuration, etc.). If you are interested in commercial support or are already receiving commercial support, feel free to contact us directly at


Codem-transcode is released under the MIT license, see LICENSE.txt.

Jump to Line
Something went wrong with that request. Please try again.