carrierwave-video

carrierwave-video copied to clipboard

= CarrierWave Video Converter

{}[http://travis-ci.org/rheaton/carrierwave-video]

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"

Also, you can preserve initial video's aspect ratio by changing one of result's resolutions: preserve_aspect_ratio: :width to change height of the video, depending on it's width (default value), preserve_aspect_ratio: :height to change width of the video, depending on it's height, or preserve_aspect_ratio: false to leave resolution unchanged

If you want to keep the same resolution:

Note: This only works with the edge version of streamio-ffmpeg (as of Feb 28, 2014) https://github.com/streamio/streamio-ffmpeg/issues/72

resolution: :same

If you want to keep the same video bitrate: video_bitrate: :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

progress: :method # method that accepts a value of progress e.g. 0.2 (20%)
                  # from https://github.com/streamio/streamio-ffmpeg#transcoding

progress can take 1 or 3 arguments. With three arguments, it receives format, format_options, and the value of progress. e.g. def progress(format, format_options, progress) would receive something like progress(:mp4, {}, 0.2)

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: %w(-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. http://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: http://www.mediasoftpro.com/aspnet-x264-presets.html Depending on how you installed ffmpeg, you need to put them in the correct directory: http://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 => %w(-qscale 0 -vpre slow -vpre baseline -g 30))