{"id":13875875,"url":"https://github.com/streamio/streamio-ffmpeg","last_synced_at":"2025-07-16T10:32:17.350Z","repository":{"id":861443,"uuid":"597162","full_name":"streamio/streamio-ffmpeg","owner":"streamio","description":"Simple yet powerful ruby ffmpeg wrapper for reading metadata and transcoding movies","archived":false,"fork":false,"pushed_at":"2024-05-08T12:47:14.000Z","size":58185,"stargazers_count":1645,"open_issues_count":67,"forks_count":413,"subscribers_count":85,"default_branch":"master","last_synced_at":"2024-11-17T14:38:21.148Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/streamio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-04-06T14:30:49.000Z","updated_at":"2024-11-12T16:04:23.000Z","dependencies_parsed_at":"2024-05-01T13:30:21.843Z","dependency_job_id":null,"html_url":"https://github.com/streamio/streamio-ffmpeg","commit_stats":{"total_commits":321,"total_committers":41,"mean_commits":7.829268292682927,"dds":0.426791277258567,"last_synced_commit":"aca5bab4adbd517b9ce1f57ec90484b6d377ff59"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamio%2Fstreamio-ffmpeg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamio%2Fstreamio-ffmpeg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamio%2Fstreamio-ffmpeg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamio%2Fstreamio-ffmpeg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/streamio","download_url":"https://codeload.github.com/streamio/streamio-ffmpeg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226122303,"owners_count":17576920,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T06:00:48.141Z","updated_at":"2024-11-24T03:31:32.103Z","avatar_url":"https://github.com/streamio.png","language":"Ruby","readme":"Streamio FFMPEG\n===============\n\n[![Build Status](https://travis-ci.org/bikeath1337/streamio-ffmpeg.svg?branch=master)](https://travis-ci.org/bikeath1337/streamio-ffmpeg)\n[![Code Climate](https://codeclimate.com/github/bikeath1337/streamio-ffmpeg/badges/gpa.svg)](https://codeclimate.com/github/bikeath1337/streamio-ffmpeg)\n[![Test Coverage](https://codeclimate.com/github/bikeath1337/streamio-ffmpeg/badges/coverage.svg)](https://codeclimate.com/github/bikeath1337/streamio-ffmpeg/coverage)\n\nSimple yet powerful wrapper around the ffmpeg command for reading metadata and transcoding movies.\n\nAll work on this project is sponsored by the online video platform [Streamio](https://streamio.com) from [Rackfish](https://www.rackfish.com).\n\n[![Streamio](http://d253c4ja9jigvu.cloudfront.net/assets/small-logo.png)](https://streamio.com)\n\nInstallation\n------------\n\n    gem install streamio-ffmpeg\n\nCompatibility\n-------------\n\n### Ruby\n\nOnly guaranteed to work with MRI Ruby 1.9.3 or later.\nShould work with rubinius head in 1.9 mode.\nWill not work in jruby until they fix: http://goo.gl/Z4UcX (should work in the upcoming 1.7.5)\n\n### ffmpeg\n\nThe current gem is tested against ffmpeg 2.8.4. So no guarantees with earlier (or much later) \nversions. Output and input standards have inconveniently changed rather a lot between versions \nof ffmpeg. My goal is to keep this library in sync with new versions of ffmpeg as they come along.\n\nOn macOS: `brew install ffmpeg`.\n\nUsage\n-----\n\n### Require the gem\n\n``` ruby\nrequire 'streamio-ffmpeg'\n```\n\n### Reading Metadata\n\n``` ruby\nmovie = FFMPEG::Movie.new(\"path/to/movie.mov\")\n\nmovie.duration # 7.5 (duration of the movie in seconds)\nmovie.bitrate # 481 (bitrate in kb/s)\nmovie.size # 455546 (filesize in bytes)\n\nmovie.video_stream # \"h264, yuv420p, 640x480 [PAR 1:1 DAR 4:3], 371 kb/s, 16.75 fps, 15 tbr, 600 tbn, 1200 tbc\" (raw video stream info)\nmovie.video_codec # \"h264\"\nmovie.colorspace # \"yuv420p\"\nmovie.resolution # \"640x480\"\nmovie.width # 640 (width of the movie in pixels)\nmovie.height # 480 (height of the movie in pixels)\nmovie.frame_rate # 16.72 (frames per second)\n\nmovie.audio_stream # \"aac, 44100 Hz, stereo, s16, 75 kb/s\" (raw audio stream info)\nmovie.audio_codec # \"aac\"\nmovie.audio_sample_rate # 44100\nmovie.audio_channels # 2\n\n# Multiple audio streams\nmovie.audio_streams[0] # \"aac, 44100 Hz, stereo, s16, 75 kb/s\" (raw audio stream info)\n\nmovie.valid? # true (would be false if ffmpeg fails to read the movie)\n```\n\n### Transcoding\n\nFirst argument is the output file path.\n\n``` ruby\nmovie.transcode(\"tmp/movie.mp4\") # Default ffmpeg settings for mp4 format\n```\n\nKeep track of progress with an optional block.\n\n``` ruby\nmovie.transcode(\"movie.mp4\") { |progress| puts progress } # 0.2 ... 0.5 ... 1.0\n```\n\nGive custom command line options with an array.\n\n``` ruby\nmovie.transcode(\"movie.mp4\", %w(-ac aac -vc libx264 -ac 2 ...))\n```\n\nUse the EncodingOptions parser for humanly readable transcoding options. Below you'll find most of the supported options.\nNote that the :custom key is an array so that it can be used for FFMpeg options like\n`-map` that can be repeated:\n\n``` ruby\noptions = {\n  video_codec: \"libx264\", frame_rate: 10, resolution: \"320x240\", video_bitrate: 300, video_bitrate_tolerance: 100,\n  aspect: 1.333333, keyframe_interval: 90, x264_vprofile: \"high\", x264_preset: \"slow\",\n  audio_codec: \"libfaac\", audio_bitrate: 32, audio_sample_rate: 22050, audio_channels: 1,\n  threads: 2, custom: %w(-vf crop=60:60:10:10 -map 0:0 -map 0:1)\n}\n\nmovie.transcode(\"movie.mp4\", options)\n```\n\nThe transcode function returns a Movie object for the encoded file.\n\n``` ruby\ntranscoded_movie = movie.transcode(\"tmp/movie.flv\")\n\ntranscoded_movie.video_codec # \"flv\"\ntranscoded_movie.audio_codec # \"mp3\"\n```\n\nAspect ratio is added to encoding options automatically if none is specified.\n\n``` ruby\noptions = { resolution: \"320x180\" } # Will add -aspect 1.77777777777778 to ffmpeg\n```\n\nPreserve aspect ratio on width or height by using the preserve_aspect_ratio transcoder option.\n\n``` ruby\nwidescreen_movie = FFMPEG::Movie.new(\"path/to/widescreen_movie.mov\")\n\noptions = { resolution: \"320x240\" }\n\ntranscoder_options = { preserve_aspect_ratio: :width }\nwidescreen_movie.transcode(\"movie.mp4\", options, transcoder_options) # Output resolution will be 320x180\n\ntranscoder_options = { preserve_aspect_ratio: :height }\nwidescreen_movie.transcode(\"movie.mp4\", options, transcoder_options) # Output resolution will be 426x240\n```\n\nFor constant bitrate encoding use video_min_bitrate and video_max_bitrate with buffer_size.\n\n``` ruby\noptions = {video_min_bitrate: 600, video_max_bitrate: 600, buffer_size: 2000}\nmovie.transcode(\"movie.flv\", options)\n```\n\n### Specifying Input Options\n\nTo specify which options apply the input, such as changing the input framerate, use `input_options` hash\nin the transcoder_options.\n\n``` ruby\nmovie = FFMPEG::Movie.new(\"path/to/movie.mov\")\n\ntranscoder_options = { input_options: { framerate: '1/5' } }\nmovie.transcode(\"movie.mp4\", {}, transcoder_options)\n\n# FFMPEG Command will look like this:\n# ffmpeg -y -framerate 1/5 -i path/to/movie.mov movie.mp4\n```\n\n### Overriding the Input Path\n\nIf FFMPEG's input path needs to specify a sequence of files, rather than a path to a single movie, transcoding_options\n`input` can be set. If this option is present, the path of the original movie will not be used.\n\n``` ruby\nmovie = FFMPEG::Movie.new(\"path/to/movie.mov\")\n\ntranscoder_options = { input: 'img_%03d.png' }\nmovie.transcode(\"movie.mp4\", {}, transcoder_options)\n\n# FFMPEG Command will look like this:\n# ffmpeg -y -i img_%03d.png movie.mp4\n```\n\n### Watermarking\n\nAdd watermark image on the video.\n\nFor example, you want to add a watermark on the video at right top corner with 10px padding.\n\n``` ruby\noptions = {\n  watermark: \"full_path_of_watermark.png\", resolution: \"640x360\",\n  watermark_filter: { position: \"RT\", padding_x: 10, padding_y: 10 }\n}\n```\n\nPosition can be \"LT\" (Left Top Corner), \"RT\" (Right Top Corner), \"LB\" (Left Bottom Corner), \"RB\" (Right Bottom Corner).\nThe watermark will not appear unless `watermark_options` specifies the position. `padding_x` and `padding_y` default to\n`10`.\n\n### Taking Screenshots\n\nYou can use the screenshot method to make taking screenshots a bit simpler.\n\n``` ruby\nmovie.screenshot(\"screenshot.jpg\")\n```\n\nThe screenshot method has the very same API as transcode so the same options will work.\n\n``` ruby\nmovie.screenshot(\"screenshot.bmp\", seek_time: 5, resolution: '320x240')\n```\n\nTo generate multiple screenshots in a single pass, specify `vframes` and a wildcard filename. Make\nsure to disable output file validation. The following code generates up to 20 screenshots every 10 seconds:\n\n``` ruby\nmovie.screenshot(\"screenshot_%d.jpg\", { vframes: 20, frame_rate: '1/6' }, validate: false)\n```\n\nTo specify the quality when generating compressed screenshots (.jpg), use `quality` which specifies\nffmpeg `-v:q` option. Quality is an integer between 1 and 31, where lower is better quality:\n\n``` ruby\nmovie.screenshot(\"screenshot_%d.jpg\", quality: 3)\n```\n\nYou can preserve aspect ratio the same way as when using transcode.\n\n``` ruby\nmovie.screenshot(\"screenshot.png\", { seek_time: 2, resolution: '200x120' }, preserve_aspect_ratio: :width)\n```\n\n### Create a Slideshow from Stills\nCreating a slideshow from stills uses named sequences of files and stiches the result together in a slideshow\nvideo.\n\nSince there is not movie to transcode, the Transcoder class needs to be used. The input and input_options are\nprovided through transcoder options.\n\n``` ruby\nslideshow_transcoder = FFMPEG::Transcoder.new(\n  '',\n  'slideshow.mp4',\n  { resolution: \"320x240\" },\n  input: 'img_%03d.jpeg',\n  input_options: { framerate: '1/5' }\n)\n\nslideshow = slideshow_transcoder.run\n```\n\nSpecify the path to ffmpeg\n--------------------------\n\nBy default, the gem assumes that the ffmpeg binary is available in the execution path and named ffmpeg and so will run commands that look something like `ffmpeg -i /path/to/input.file ...`. Use the FFMPEG.ffmpeg_binary setter to specify the full path to the binary if necessary:\n\n``` ruby\nFFMPEG.ffmpeg_binary = '/usr/local/bin/ffmpeg'\n```\n\nThis will cause the same command to run as `/usr/local/bin/ffmpeg -i /path/to/input.file ...` instead.\n\n\nAutomatically kill hung processes\n---------------------------------\n\nBy default, the gem will wait for 30 seconds between IO feedback from the FFMPEG process. After which an error is logged and the process killed.\nIt is possible to modify this behaviour by setting a new default:\n\n``` ruby\n# Change the timeout\nTranscoder.timeout = 10\n\n# Disable the timeout altogether\nTranscoder.timeout = false\n```\n\nDisabling output file validation\n------------------------------\n\nBy default Transcoder validates the output file, in case you use FFMPEG for HLS\nformat that creates multiple outputs you can disable the validation by passing\n`validate: false` to transcoder_options.\n\nNote that transcode will not return the encoded movie object in this case since\nattempting to open a (possibly) invalid output file might result in an error being raised.\n\n```ruby\ntranscoder_options = { validate: false }\nmovie.transcode(\"movie.mp4\", options, transcoder_options) # returns nil\n```\n\nCopyright\n---------\n\nCopyright (c) Rackfish AB. See LICENSE for details.\n","funding_links":[],"categories":["Ruby","others","Video","etc"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreamio%2Fstreamio-ffmpeg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstreamio%2Fstreamio-ffmpeg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreamio%2Fstreamio-ffmpeg/lists"}