media_trim Gem Version

Trims an audio or video file using ffmpeg.

  • Works with all formats supported by ffmpeg, including mp3, mp4, mkv, and many more.
  • Seeks to the nearest frame positions by re-encoding the media.
  • Reduces file size produced by OBS Studio by over 80 percent.
  • Can be used as a Ruby gem.
  • Installs the trim command.

Installation

You need a working Ruby environment to install this program. I describe how to set that up here.

Standalone

The trim command is provided by the media_trim Ruby gem. Install it like this:

$ gem install media_trim

As a Dependency of a Ruby Program

Add this line to your application’s Gemfile:

gem 'media_trim'

Then execute:

$ bundle

As a Dependency of a Ruby Gem

Add the following to your application’s .gemspec:

spec.add_dependency 'media_trim'

Then execute:

$ bundle

Usage

Command-line Usage

trim [OPTIONS] dir/file.ext start [[to|for] end]
  • The start and end timecodes have the format [HH:[MM:]]SS[.XXX]. Note that decimal seconds may be specified, but frames may not; this is consistent with how ffmpeg parses timecodes.
  • end defaults to the end of the audio/video file

When run as a command, output files are named by adding a trim. prefix to the media file name, e.g. dir/trim.file.ext. By default, the trim command does not overwrite pre-existing output files. When trimming is complete, the trim command displays the trimmed file, unless the -V option is specified.

OPTIONS are:

  • -d Enable debug output.
  • -h Display help information.
  • -f Overwrite output file if present.
  • -v Verbose output.
  • -V Do not view the trimmed file when complete.
  • -H Disable hardware acceleration and use software decoding. If hardware acceleration cannot be initialized on your system, the command will automatically retry using software decoding. Software decoding may be slower but will produce the same output. If a required software decoder is missing the program will halt and display a clear error message.

Preflight checks

Before running ffmpeg the trim command performs a set of preflight checks and reports any issues in clear English sentences. The checks include:

  • Verifying the ffmpeg executable is available; if it is not installed the command aborts with instructions to install it.
  • Probing hardware acceleration initialization; if hardware acceleration initialization fails the tool will warn you and retry in software mode.
  • Verifying that ffmpeg can perform a short software decode of the input file; if software decoding fails the command will abort as this indicates a missing decoder or an unreadable input file.
  • Checking there is sufficient disk space in the destination directory; the command aborts if there is not enough free space.

These checks ensure the tool halts on fatal problems and otherwise produces a successful result using software decoding when needed.

Examples

Crop dir/file.mp4 from 15.0 seconds to the end of the video, save to demo/trim.demo.mp4:

$ trim demo/demo.mp4 15

Crop dir/file.mkv from 3 minutes, 25 seconds to 9 minutes, 35 seconds, save to demo/trim.demo.mp4:

$ trim demo/demo.mp4 3:25 9:35

Same as the previous example, using optional to syntax:

$ trim demo/demo.mp4 3:25 to 9:35

Save as the previous example, but specify the duration instead of the end time by using the for keyword:

$ trim demo/demo.mp4 3:25 for 6:10

Figuring Out Start and Stop Times

Need a way to figure out the start and stop times to trim a video? DJV is an excellent video viewer.

  • Allows frame-by-frame stepping
  • Displays the current time reliabily
  • F/OSS
  • Mac, Windows, Linux
  • High quality

Development

After checking out this git repository, install dependencies by typing:

$ bin/setup

You should do the above before running Visual Studio Code.

Run the Tests

$ bundle exec rake test

Interactive Session

The following will allow you to experiment:

$ bin/console

Local Installation

To install this gem onto your local machine, type:

$ bundle exec rake install

To Release A New Version

To create a git tag for the new version, push git commits and tags, and push the new version of the gem to https://rubygems.org, type:

$ bundle exec rake release

Contributing

Bug reports and pull requests are welcome at https://github.com/mslinn/trim.

License

The gem is available as open source under the terms of the MIT License.