Project: muvy - The Ruby Toolbox

muvy-header

muvy is a simple Ruby movie barcode generator.
You can feed it a youtube video, phone gallery, or any locally stored video files. It pulls the frames out, moves around the colors, and throws them back together in a neat montage.

Install
- Notes
- Getting Started
Usage
- Basics
- Options
- Features
Examples
Troubleshooting
Links

Install

Changelog

- Full support for YouTube and more support for other sites (Vimeo with --format bestvideo or similar, etc).
- Many features still planned!

Getting Started

macOS

You can use ffmpeg -v, convert -v, or youtube-dl --version at the terminal to check if you already have the binaries.
If you don't already have FFmpeg, ImageMagick, or youtube-dl installed, you can download all of them with Homebrew. With Homebrew, just bring up a terminal session and type:

$ brew install ffmpeg
$ brew install imagemagick
$ brew install youtube-dl
$ gem install muvy

Windows

Install Ruby
Install Windows binaries for ImageMagick, noting:
On the third installation window, check these 2 boxes:
- Add application directory to your system path
- Install legacy utilities (e.g. convert)
- Keep 'Install FFmpeg' unchecked. IM's bundle doesn't include ffprobe & ffplay
Install FFmpeg
You'll have to manually edit your PATH environment variable like in this tutorial. After setting up FFmpeg in the PATH, bring up the 'envrionment variables' window. Move the ImageMagick folder from 'User Variables' to the first entry in the 'System Variables' so that Windows prefers ImageMagick convert over its own 'convert.exe'. Here's an image showing that process
ImageMagick 7 replaced convert with magick on Windows, but this gem can't make use of that yet.
Install youtube-dl.
Then, you can install any gem like so:

$ gem install muvy

Usage

Basics

Type	Command: `muvy [Type] [Options]`	Support
URL	`muvy https://youtube.com/someVidID`	youtube-dl sites, but many fail
Local	`muvy /Documents/Fave-Films/movie.mp4`	FFmpeg supported formats
Folder	`muvy /Downloads/Phone-Backup-1/Photos`	ImageMagick supported formats

Options

`-p, --path`

Optionally specify the path where your final image will be saved.
Default: your present working directory

`-s, --style`

Optionally specify currently supported styles.
Styles: solid, stretch
Default: solid

`-g, --gradient`

Optionally add a gradient on top of the final image.
Styles:
black:heavy black:medium black:light
white:heavy white:medium white:light
Default: none

`-a, --arc`

Arc all of the colored lines around the center point.
Styles: circle, iris (annulus)
Default: none

`-r, --rotate`

Pass to rotate the final image 90 degrees to draw horizontal lines, where the top is the 'start' of the media.
Default: none (vertical lines)

`-h, --height`

Optionally specify a custom height for the output image.

`--format`

Optionally force the download quality for youtube-dl.
Determines the height of your image when using --style stretch only if you didn't specify --height.
Default: 135 corresponds to 854x480 DASH at 24fps

The default is currently best-suited to YouTube and will likely not work with other sites. To see possible formats for other sites, type youtube-dl -F <URL> or see youtube-dl docs on format selection. For example, with a Vimeo video, you might specify --format bestvideo or --format worstvideo and it should work. youtube-dl is sometimes picky, so it is not guaranteed!

`--frame_rate`

Optionally specify the amount of frames to extract per second from the media.
Determines the width of the image.

You should run muvy [..] without this option once and check the stats printout to get an idea of a better number.
For example, if the stats printout reads "1.6 fps," passing --frame_rate 3.2 would double the amount of frames, lines, and subsequently the width.

Setting this to an unreasonable number might cause hundreds of thousands of files to be temporarily created in your system's temp files.

`--start` and `--end`

Optionally specify starting and ending times for processing videos.
If you only specify one, the other will default. For example, if you only pass --end N, start defaults to 0.

Features

Formats
- Accepts image galleries, local videos, and online videos
  - Works with any size image folder (very large folders cause output issues)
  - Works with any youtube-dl supported site
  - Specify start & end times for frame extraction
- Accept music files
  - Generate audio waveforms
  - Randomize waveform colors
Image Output
- Vertical lines
- Horizontal lines
- 'Stretched' output, taking average of each line of pixels
- Arc distortion
- Spotmap output, akin to 'QR' code
- Slit scan output
- 'Bedforms' output
- Stacked lines output, inspired by Sol Lewitt
  - Choose inset borders
  - Curvature
- Crosshatch lines output
Image adjustments
- Fade to black or white on edges
- Pixel thickness control
- Colorspace changes
Generation
- Dominant color algorithms
  - via ImageMagick histograms
  - via k-means clustering
Compatibility
- Use popen3 since current gem wrappers are outdated (TODO)

Examples

Films

Spirited Away (2001)

muvy film.mkv -h 300

0.27 frames per second on 125 minutes
final resolution 2027x300

Mad Max: Fury Road (2015)

muvy madden.mkv --end 01:52:50 -h 300

0.276 frames per second on 120 minutes
final resolution 1868x300

The Grand Budapest Hotel (2014)

muvy "grand.avi" --end 01:33:40 --gradient black:medium --height 600

0.303 frames per second on 100 minutes
final resolution 1703x600

Her (2013)

muvy film.mp4 -g black:medium -h 720

0.269 frames per second on 126 minutes
final resolution 1919x720

Melancholia (2011)

muvy film.mp4 --gradient black:medium

0.277 frames per second on 136 minutes
final resolution 2158x720

Kagemusha (1980)

muvy film.mp4 --style stretch --gradient black:medium

0.225 frames per second on 162 minutes
final resolution 2439x688

Samsara (2011)

(1) muvy film.avi --end 01:35:00 -s stretch -g black:medium

(2) muvy film.avi --height 150 --end 01:35:00

0.3 frames per second on 95 minutes

Baraka (1992)

muvy film.avi --height 150 --end 01:30:30

0.3 frames per second on 90 minutes
final resolution 1663x150

It's Such A Beautiful Day (2012)

muvy film.mkv --height 200

0.4843 frames per second on 62 minutes
final resolution 1780x720

YouTube

Holi by Variable

muvy https://www.youtube.com/watch?v=r64Xk7c4Mr4 --frame_rate 10 --style stretch

slow-motion youtube video
10 frames per second on 1 minute 47 seconds
final resolution 1073x480

Mahalia - Sober by COLORS

(1) muvy https://www.youtube.com/watch?v=QK7JQl9jNzM --frame_rate 7.5 --start 0:05 --end 3:23 -h 200

(2) muvy https://www.youtube.com/watch?v=QK7JQl9jNzM --frame_rate 7.5 --start 0:05 --end 3:23 -s stretch

7.5 frames per second on 3 minutes 36 seconds

The Banach–Tarski Paradox by Vsauce

muvy https://www.youtube.com/watch?v=s86-Z-CbaHA

0.62 frames per second on 24 minutes 14 seconds
final resolution 898x720

Colors In Macro by Macro Room

muvy https://www.youtube.com/watch?v=gNbSjMFd7j4 --start 0:16 --end 2:07 --style stretch --frame_rate 10

10 frames per second on ~ 2 minutes
final resolution 1110x480

Ink In Motion by Macro Room

(1) muvy https://www.youtube.com/watch?v=BmBh0NNEm00 --start 0:37 --end 1:20 --frame_rate 10 -s stretch -a circle

(2) muvy https://www.youtube.com/watch?v=BmBh0NNEm00 --start 0:37 --end 1:20 --frame_rate 10 -r --arc circle

Speed Drawing

(1) muvy https://www.youtube.com/watch?v=P3UozWhL6A0 --start 0:04 --end 04:45 --arc circle

(2) muvy https://www.youtube.com/watch?v=P3UozWhL6A0 --start 0:04 --end 04:45 --arc circle -r

1.7185 frames per second
final resolution 872x872

The following iris examples had colored backgrounds added to them in post.

Kurzgesagt - The Rise of the Machines

(1) muvy https://www.youtube.com/watch?v=WSKi8HfcxEk --arc iris

(2) muvy https://www.youtube.com/watch?v=WSKi8HfcxEk --arc iris --rotate

1.1154 frames per second on 11:40
final resolution 1082x1082

Kurzgesagt - Why Age? Should We End Aging Forever?

(1) muvy https://www.youtube.com/watch?v=GoJsr4IwCm4 --arc iris

(2) muvy https://www.youtube.com/watch?v=GoJsr4IwCm4 --arc iris --rotate

1.463 frames per second on 06:48
final resolution 1082x1082

Kurzgesagt - Death From Space — Gamma-Ray Bursts Explained

muvy https://www.youtube.com/watch?v=RLykC1VN7NY --arc iris

1.4186 frames per second on 07:13
final resolution 1082x1082

DCIM

DCIM merging is currently a bit buggy in that it will create extra random lines if it's very low on memory (usually occurs when feeding thousands of 16MP+ photos).

2016 Travel

muvy imagefolder/

2350 photos

Troubleshooting

Make sure you can access ffmpeg -v, convert -v, and youtube-dl --version on the command line. If you can't, you likely have to update your existing PATH environment variable to include the folder holding the relevant binaries. If you're on Windows and you are unsure how to add FFmpeg to path, you can try any of these links: 1, 2, 3.

If you're on Windows and very recently made changes, you probably have to reopen a command prompt window or restart for those changes to take effect.

You might also want to update all three binaries.

If it's not working out, I've linked more generators and methods that you can try out, most of them depending on some combination of ffmpeg and ImageMagick.

muvy

Development

Runtime