Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
carrierwave extension to use ffmpeg to transcode videos to html5-friendly format
Ruby
Branch: master
Pull request Compare This branch is 29 commits behind rheaton:master.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.gitignore
.travis.yml
Gemfile
README.rdoc
Rakefile
carrierwave-video.gemspec

README.rdoc

CarrierWave Video Converter

Build Status

This gem adds a video converter using ffmpeg and the streamio-ffmpeg rubygem.

Installation

gem install carrierwave-video

Using bundler:

gem 'carrierwave-video'

Usage

class VideoUploader < CarrierWave::Uploader::Base
  include CarrierWave::Video

  process encode_video: [:mp4, callbacks: { after_transcode: :set_success } ]
end

class Video
  mount_uploader :file, VideoUploader

  def set_success(format, opts)
    self.success = true
  end
end

Possible Options

Pass in options to process:

process encode_video: [:mp4, resolution: "200x200"]

Resolution passed to ffmpeg:

resolution: "640x360"

If you want to keep the same resolution:

resolution: :same

Watermark:

watermark: {
  path: File.join(Rails.root, "directory", "file.png"),
  position: :bottom_right, # also: :top_right, :bottom_left, :bottom_right
  pixels_from_edge: 10
}

Callbacks: These are methods defined on the model. They will be run as part of the transcoding process. Useful for notating failure and completion. They will be called with the parameters sent to process.

callbacks: {
  before_transcode: :method
  after_transcode: :method
  rescue: :method
  ensure: :method
}

Logging:

logger: :method  #returns object that behaves like Logger

Custom: streamio-ffmpeg accepts custom params. You may pass these in but keep in mind the watermarking params will be appended if there were any.

custom: '-b 1500k'

Dynamic Configuration

class VideoUploader < CarrierWave::Uploader::Base
  include CarrierWave::Video

  DEFAULTS = {
    watermark: {
      path: Rails.root.join('watermark-large.png')
    }
  }

  process :encode

  def encode
    encode_video(:mp4, DEFAULTS) do |movie, params|
      if movie.height < 720
        params[:watermark][:path] = Rails.root.join('watermark-small.png')
      end
    end
  end
end

OGG/OGV & Theora

If you want to transcode to OGV format, I recommend using ffmpeg2theora. It works better. Support for this is built into this gem, but it is not as mature as the transcoding support built into the streamio-ffmpeg gem. You will need to install the ffmpeg2theora binary. v2v.cc/~j/ffmpeg2theora/

ffmpeg2theora does not have watermark support, so if you want a watermark, I recommend building the theora file off previous version. I have not built in resolution or any other options as I am just creating mine from a previous version (in the correct size/with watermark). If you need support for this it shouldn't be too hard to add. (Use streamio-ffmpeg for inspiration)

Example:

class VideoUploader < CarrierWave::Uploader::Base
  include CarrierWave::Video

  version :mp4 do
    process :encode_video => [:mp4, {...}]
  end

  version :ogv, :from_version => :mp4 do
    process :encode_ogv => [{ logger: logger_method, callbacks: {...}  }]
  end
end

You do not need to pass in the format to the encode_ogv method (as it is always ogv). The only options that do work are logger and callbacks. Others will be ignored.

ffmpeg installation notes:

Installing with homebrew on OSX will get a nice configuration that works with this gem (including libx264 and libfaac for mp4's and libvorbis and libvpx for webm). The default quality of the libtheora and libvorbix ogv defaults is poor, but installed with the default homebrew. As mentioned above, you can use ffmpeg2theora.

The default custom params for mp4 encoding use presets. You can change the custom params to use whatever you want, but the presets are supposed to give a better video quality. The preset files are here: www.mediasoftpro.com/aspnet-x264-presets.html Depending on how you installed ffmpeg, you need to put them in the correct directory: ffmpeg.org/ffmpeg.html#Preset-files

Upcoming and notes

  • ffmpeg gives a confusing error if watermark file does not exist, raise in ruby

  • error handling/checking (extract from streamio-ffmpeg gem's transcoder) for encode_ogv

NOTE: For older versions of ffmpeg, the -preset flag was called -vpre. If you are using a version prior to 0.11, you must call carrierwave-video using the custom option to change those flags. Something along the lines of:

encode_video(:mp4, :custom => '-qscale 0 -vpre slow -vpre baseline -g 30')
Something went wrong with that request. Please try again.