make_video: Create video from sequence of still images

In jsta/glatos: A package for the Great Lakes Acoustic Telemetry Observation System

Create video from sequence of still images

Description

Stitch a sequence of images into a video animation using FFmpeg software.

Usage

make_video(dir = getwd(), pattern, output = "animation.mp4",
  output_dir = getwd(), fps_in = 30, start_frame = 1,
  end_frame = NULL, size = "source", preset = "medium",
  codec = "default", format = "yuv420p", lossless = FALSE,
  fps_out = 30, overwrite = FALSE, ffmpeg = NA,
  diagnostic_mode = FALSE)

Arguments

dir	directory containing images, default is working directory.
pattern	character, pattern for matching image file names. See details.
output	character, output file name. See details.
output_dir	output directory, default is working directory, but will be created if it does not exist.
fps_in	integer, intended framerate of input image sequence in frames per second.
start_frame	integer, start frame. Defaults to start=1.
end_frame	integer, end frame. Defaults to end_frame = NULL.
size	character, the dimensions of the video output. Defaults to "source", which is equal to the dimensions of the input files. Otherwise scaling is performed on the output. See details.
preset	character, encoding presets available in FFmpeg. Defaults to medium. See details.
codec	character, video codec used. See details.
format	character, pixel format used. See details.
lossless	logical, use lossless H.264 encoding if applicable. Defaults to FALSE. See details.
fps_out	integer, framerate of animation in frames per second.
overwrite	logical, overwrite existing output file?
ffmpeg	A file path (characer) to FFmpeg executable. This argument is only needed if ffmpeg is not added to your system path. For Windows machines, path must point to 'ffmpeg.exe', located in the bin subfolder within the ffmpeg folder. For example on Windows machines, "C:/Users/Username/Documents/ffmpeg-3.4.1-win64-static/bin/ffmpeg.exe"). On Mac, path must point to 'ffmpeg' within the 'bin' subfolder "/home/directory/Documents/bin/ffmpeg".
diagnostic_mode	Logical (default = FALSE). If true, return value is a character vector with FFMPEG output.

Details

make_video is based on mapmate::ffmpeg. More information about mapmate package is found at https://github.com/leonawicz/mapmate. This function converts R syntax into command line call that is submitted to ffmpeg. ffmpeg must be installed and able to be accessed by the system command line prior to running make_video. See https://www.ffmpeg.org for information on installing ffmpeg.

The FFmpeg multimedia framework provides extensive flexibility and options for converting and manipulating video and audio content. make_video provides a small subset of options useful for creating simple animated videos. If additional flexibility or options are needed, the user may need to develop or modify make_video or submit calls directly to FFmpeg using the system command line.

Sequenced image files are input into FFmpeg using a file name convention which requires specifying the entire, non-changing file name with a consecutive integer numbering component. The integer number component indicates the maximum number of digits of all the images. For example, %04d.png represents the file numbering 0000.png, 0001.png, 0002.png, ..., 9999.png and %02d.png represents images numbered from 00.png, 01.png, 02.png, ..., 10.png. File names of image sequences input to FFmpeg may have a prefix provided that all image files have the sequence. For example an image sequence of myfile001.png, myfile002.png, myfile003.png, ..., myfile999.png is represented as myfile%03d.png. pattern only accepts this pattern of image file names.

Function can create .mp4, .mov, .mkv, .gif, .wmv, or .mpeg animations. Format of created animation is determined by file extension of output.

make_video allows user to specify input framerate fps_in of image sequence and output fps_out framerate of animation.

start_frame specifies starting frame in animation and end_frame specifies end frame in animation. If start_frame and end_frame are specified, only images within range are used in animation. Specifying start_frame and end_frame allows user to skip images.

If size is not set to "source", the output video is scaled. size can be a character string of dimensions in length by height format such as "720x480" or an abbreviated standard such as "ntsc". See FFmpegstandard video sizes for common dimensions and available abbreviations.

Presets provide a certain encoding speed to compression ratio. Available presets include ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow. Faster preset i.e.(ultrafast) corresponds to greater file size, lower animation quality, and faster computation times. Slower speeds veryslow corresponds to smaller file, higher quality animation and slower computation times. See http://trac.ffmpeg.org/wiki/Encode/H.264

@details codec is ignored if the file name in pattern ends with .gif. For other video output file types a default codec is used depending on the file extension of output animation.These can be overridden with options like codec="h264", "libx264", "libvpx", "prores", "qtrle", etc., but the user needs to be knowledgeable regarding which codecs can be used for which output types or errors will be thrown.

format is ignored if the file name in pattern ends with .gif. The default is "yuv420p", which performs 4:2:0 chroma subsampling. This pixel format can reduce video quality, but it is the default because it ensures compatibility with most media players. For valid alternatives, run system("ffmpeg -pix_fmts").

lossless is ignored except for relevant codec settings, e.g., h264 or libx264. If TRUE, recommended preset values are ultrafast or veryslow. See https://trac.ffmpeg.org/wiki/Encode/H.264 for more information.

Value

One video animation will be written to output_dir

Author(s)

Todd Hayden, Tom Binder, Chris Holbrook

Examples

## Not run: 

# load frames
frames <- system.file("extdata", "frames", package = "glatos")

# make .mp4 video
# make sure ffmpeg is on system path (see \code{make_frames} and details)
make_video(dir = frames, pattern = "%02d.png", output = "animation.mp4"  )

# make .wmv video
make_video(dir=frames, pattern = "%02d.png", output = "animation.wmv" )

# start animation on frame 10, end on frame 20
make_video(dir=frames, pattern = "%02d.png", start_frame = 10, 
           end_frame = 20, output = "animation_2.mp4")

# resize output video to 720x480
make_video(dir=frames, pattern = "%02d.png", size = "720x480", 
           output = "animation_3.mp4" )

# change ffmpeg preset
make_video(dir=frames, pattern = "%02d.png", preset = "ultrafast", 
           output = "animation_4.mp4")

# change input framerate
make_video(dir=frames, fps_in = 1, pattern = "%02d.png", 
           preset = "ultrafast", output = "animation_5.mp4")


# add path to ffmpeg (windows)
make_video(dir = frames, pattern = "%02d.png", output = "animation.mp4", 
           ffmpeg = "c://path//to//windows//ffmpeg.exe")

# add path to ffmpeg (mac)
make_video(dir = frames, pattern = "%02d.png", output = "animation.mp4", 
           ffmpeg = "/path/to/ffmpeg")

## End(Not run)

jsta/glatos documentation built on July 11, 2022, 7:01 a.m.