Commit 362b60de authored by Chris Holbrook's avatar Chris Holbrook

wrap up conversion to av and compability for legacy ffmpeg-based make_video

parent 696df635
......@@ -22,7 +22,6 @@ export(make_transition)
export(make_transition2)
export(make_transition3)
export(make_video)
export(make_video_av)
export(min_lag)
export(point_offset)
export(position_heat_map)
......
This diff is collapsed.
##' Create video from sequence of still images
##'
##' Stitch a sequence of images into a video animation using R package "av"
##'
##' @param dir directory containing images, default is working
##' directory.
##' @param ext character, file extension of images to be stitched into
##' a video.
##' @param output character, output video file name. See details.
##' @param fps_in integer, intended framerate of input image sequence
##' in frames per second.
##' @param start_frame integer, start frame. Defaults to
##' \code{start=1}.
##' @param end_frame integer, end frame. Defaults to \code{end_frame
##' = NULL}.
##' @param codec character, video codec used.
##' @param verbose Logical (default = FALSE). If true, returns details
##' of processing.
##' @param audio audio or video input file with sound for the output
##' video.
##' @param vfilter a string defining an ffmpeg filter. This is the
##' same parameter as the -vf argument in FFmpeg.
##'
##' @details This function stitches a sequence of images into a video
##' without an external installation of FFmpeg software.
##' \code{make_video_av} is a simple wrapper of
##' \code{av_encode_video}. More information about the \code{av}
##' package is available at
##' https://cran.r-project.org/web/packages/av/index.html and
##' https://docs.ropensci.org/av/.
##'
##' @details The argument \code{codec} defaults to \code{libx264} for
##' most formats which is usually the best choice. More information
##' about other available codecs can be found by running
##' \code{av::av_encoders}. The argument \code{vfilter} is used to
##' specify FFmpeg filters to modify video output.
##' \code{av::av_filters()} function lists the possible filters
##' available. More information and examples of using filters to
##' manipulate video output can be found at
##' https://trac.ffmpeg.org/wiki/FilteringGuide#Examples
##'
##' @details A directory of sequenced image files (.png, .jpeg) are
##' passed to \code{dir} argument. The \code{ext} argument
##' specifies the type of files to be stitched into a video. The
##' images passed to the function must all have the same size,
##' height, and format.
##'
##' @details Function can create .mp4, .mov, .mkv, .flv .wmv, or
##' .mpeg animations. Format of created animation is determined by
##' file extension of \code{output}.
##'
##' @details \code{make_video_av} allows user to specify input
##' framerate \code{fps_in} of image sequence and specify the
##' starting and ending frames (\code{start_frame},
##' \code{end_frame}). If specified, only images within range are
##' used in animation and all other frames are skipped.
##'
##' @details
##'
##' @return One video animation will be written to \code{output_dir}
##'
##' @author Todd Hayden, Tom Binder, Chris Holbrook
##'
##' @examples
##'
##' \dontrun{
##'
##' # load frames
##' frames <- system.file("extdata", "frames", package = "glatos")
##'
##' # make .mp4 video
##' make_video_av(dir = frames, ext = ".png", output = "animation1.mp4", verbose = FALSE)
##'
##' # make .wmv video
##' make_video_av(dir=frames, ext = ".png", output = "animation2.wmv", verbose = TRUE)
##'
##' # start animation on frame 10, end on frame 20
##' make_video_av(dir=frames, ext = ".png", start_frame = 10,
##' end_frame = 20, output = "animation_3.mp4")
##'
##'# make move backwards- start animation of frame 20 and end on frame 10
##' make_video_av(dir=frames, ext = ".png", start_frame = 20,
##' end_frame = 10, output = "animation_4.mp4")
##'
##' # resize output video by specifying a scale filter
##' make_video_av(dir=frames, ext= ".png", vfilter = "scale=320:240",
##' output = "animation_5.mp4" )
##'
##' # slow the video by 10 times
##' make_video_av(dir=frames, ext= ".png", vfilter = "setpts=10*PTS",
##' output = "animation_6.mp4" )
##'
##' # slow video by 10 times and scale to 320x240 resolution
##' make_video_av(dir=frames, ext = ".png",
##' vfilter = "scale=320:240, setpts=10*PTS", output = "animation_7.mp4")
##'
##' # slow video by 10 times and smooth movement
##' make_video_av(dir=frames, ext = ".png", vfilter = "minterpolate='mi_mode=mci:mc_mode=aobmc:vsbmc=1:fps=120', setpts=10*PTS", output = "animation_8.mp4")
##'
##' # change input framerate
##' make_video_av(dir=frames, ext = ".png", fps_in = 5,
##' output = "animation_9.mp4")
##'
##' }
##'
##' @export
make_video_av <- function(...){
# makes vector of images
ext <- paste0("*", ext)
files <- list.files(dir, full.names = TRUE, pattern = ext)
#check if dir exists
if(!dir.exists(dir)) stop(paste0("Input dir '", dir , "' not found."),
.call = FALSE)
# subset out frames if needed
if(is.null(end_frame)){end_frame <- length(files)}
fls <- files[start_frame:end_frame]
if(is.null(vfilter)){vfilt <- "null"} else {vfilt <- vfilter}
av::av_encode_video(input = fls, output = output, framerate = fps_in, vfilter = vfilt, codec = codec, verbose = verbose, audio = audio)
message("Video file written to ", output, ".")
}
This diff is collapsed.
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vis-make_video_av.r
\name{make_video_av}
\alias{make_video_av}
\title{Create video from sequence of still images}
\usage{
make_video_av(
dir = getwd(),
ext = ".png",
output = "animation.mp4",
fps_in = 30,
start_frame = 1,
end_frame = NULL,
codec = NULL,
vfilter = NULL,
verbose = TRUE,
audio = NULL
)
}
\arguments{
\item{dir}{directory containing images, default is working
directory.}
\item{ext}{character, file extension of images to be stitched into
a video.}
\item{output}{character, output video file name. See details.}
\item{fps_in}{integer, intended framerate of input image sequence
in frames per second.}
\item{start_frame}{integer, start frame. Defaults to
\code{start=1}.}
\item{end_frame}{integer, end frame. Defaults to \code{end_frame
= NULL}.}
\item{codec}{character, video codec used.}
\item{vfilter}{a string defining an ffmpeg filter. This is the
same parameter as the -vf argument in FFmpeg.}
\item{verbose}{Logical (default = FALSE). If true, returns details
of processing}
\item{audio}{audio or video input file with sound for the output
video}
}
\value{
One video animation will be written to \code{output_dir}
}
\description{
Stitch a sequence of images into a video animation using R package "av"
}
\details{
This function stitches a sequence of images into a video
without an external installation of FFmpeg software.
\code{make_video_av} is a simple wrapper of
\code{av_encode_video}. More information about the \code{av}
package is available at
https://cran.r-project.org/web/packages/av/index.html and
https://docs.ropensci.org/av/.
The argument \code{codec} defaults to \code{libx264} for
most formats which is usually the best choice. More information
about other available codecs can be found by running
\code{av::av_encoders}. The argument \code{vfilter} is used to
specify FFmpeg filters to modify video output.
\code{av::av_filters()} function lists the possible filters
available. More information and examples of using filters to
manipulate video output can be found at
https://trac.ffmpeg.org/wiki/FilteringGuide#Examples
A directory of sequenced image files (.png, .jpeg) are
passed to \code{dir} argument. The \code{ext} argument
specifies the type of files to be stitched into a video. The
images passed to the function must all have the same size,
height, and format.
Function can create .mp4, .mov, .mkv, .flv .wmv, or
.mpeg animations. Format of created animation is determined by
file extension of \code{output}.
\code{make_video_av} allows user to specify input
framerate \code{fps_in} of image sequence and specify the
starting and ending frames (\code{start_frame},
\code{end_frame}). If specified, only images within range are
used in animation and all other frames are skipped.
}
\examples{
\dontrun{
# load frames
frames <- system.file("extdata", "frames", package = "glatos")
# make .mp4 video
make_video_av(dir = frames, ext = ".png", output = "animation1.mp4", verbose = FALSE)
# make .wmv video
make_video_av(dir=frames, ext = ".png", output = "animation2.wmv", verbose = TRUE)
# start animation on frame 10, end on frame 20
make_video_av(dir=frames, ext = ".png", start_frame = 10,
end_frame = 20, output = "animation_3.mp4")
# make move backwards- start animation of frame 20 and end on frame 10
make_video_av(dir=frames, ext = ".png", start_frame = 20,
end_frame = 10, output = "animation_4.mp4")
# resize output video by specifying a scale filter
make_video_av(dir=frames, ext= ".png", vfilter = "scale=320:240",
output = "animation_5.mp4" )
# slow the video by 10 times
make_video_av(dir=frames, ext= ".png", vfilter = "setpts=10*PTS",
output = "animation_6.mp4" )
# slow video by 10 times and scale to 320x240 resolution
make_video_av(dir=frames, ext = ".png",
vfilter = "scale=320:240, setpts=10*PTS", output = "animation_7.mp4")
# slow video by 10 times and smooth movement
make_video_av(dir=frames, ext = ".png", vfilter = "minterpolate='mi_mode=mci:mc_mode=aobmc:vsbmc=1:fps=120', setpts=10*PTS", output = "animation_8.mp4")
# change input framerate
make_video_av(dir=frames, ext = ".png", fps_in = 5,
output = "animation_9.mp4")
}
}
\author{
Todd Hayden, Tom Binder, Chris Holbrook
}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vis-make_video.r
\name{make_video_ffmpeg}
\alias{make_video_ffmpeg}
\title{Create video from sequence of still images using ffmpeg.exe}
\usage{
make_video_ffmpeg(
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{
\item{dir}{directory containing images, default is working
directory.}
\item{pattern}{character, pattern for matching image file names.
See details.}
\item{output}{character, output file name. See details.}
\item{output_dir}{output directory, default is working directory, but will
be created if it does not exist.}
\item{fps_in}{integer, intended framerate of input image sequence
in frames per second.}
\item{start_frame}{integer, start frame. Defaults to
\code{start=1}.}
\item{end_frame}{integer, end frame. Defaults to \code{end_frame
= NULL}.}
\item{size}{character, the dimensions of the video
output. Defaults to \code{"source"}, which is equal to the
dimensions of the input files. Otherwise scaling is performed on
the output. See details.}
\item{preset}{character, encoding presets available in
FFmpeg. Defaults to \code{medium}. See details.}
\item{codec}{character, video codec used. See details.}
\item{format}{character, pixel format used. See details.}
\item{lossless}{logical, use lossless H.264 encoding if
applicable. Defaults to \code{FALSE}. See details.}
\item{fps_out}{integer, framerate of animation in frames per
second.}
\item{overwrite}{logical, overwrite existing output file?}
\item{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".}
\item{diagnostic_mode}{Logical (default = FALSE). If true, return value
is a character vector with FFMPEG output.}
}
\value{
One video animation will be written to \code{output_dir}
}
\description{
Stitch a sequence of images into a video animation using FFmpeg
software. \strong{NOTE: This function is DEPRECATED and is being maintained
temporarily for backward compatibility with glatos v. 0.4.0 and earlier.}
\emph{Use \link[glatos]{make_video} instead.} See details.
}
\details{
\strong{This function is DEPRECATED and is being maintained
temporarily for backward compatibility with glatos v. 0.4.0 and earlier.}
\emph{Use \link[glatos]{make_video} instead.} This function was previously
named \code{make_video}. Starting with glatos v. 0.4.1,
\link[glatos]{make_video} was changed to simplify inputs and to use the
\code{av} package function \link[=encoding]{av::av_encode_video} instead
of external program ffmpeg. For backward-compatibility, any calls to
\link[glatos]{make_video} with arguments from the earlier version of the
function will be redirected here (\code{make_video_ffmpeg}).
\code{make_video_ffmpeg} is based on \code{mapmate::ffmpeg}.
More information about \code{mapmate} package is found at
\code{https://github.com/leonawicz/mapmate}. This function
converts R syntax into command line call that is submitted to
\code{ffmpeg}. \code{ffmpeg} must be installed and able to be
accessed by the system command line prior to running
\code{make_video_ffmpeg}. See \code{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. \code{make_video_ffmpeg} 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 \code{make_video_ffmpeg} 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, \code{\%04d.png} represents the file numbering \code{0000.png,
0001.png, 0002.png, ..., 9999.png} and \code{\%02d.png} represents images
numbered from \code{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
\code{myfile001.png, myfile002.png, myfile003.png, ..., myfile999.png} is
represented as \code{myfile\%03d.png}. \code{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 \code{output}.
\code{make_video_ffmpeg} allows
user to specify input framerate \code{fps_in} of image sequence
and output \code{fps_out} framerate of animation.
\code{start_frame} specifies starting frame in animation
and \code{end_frame} specifies end frame in animation. If
\code{start_frame} and \code{end_frame} are specified, only
images within range are used in animation. Specifying
\code{start_frame} and \code{end_frame} allows user to skip
images.
If \code{size} is not set to \code{"source"}, the output video is
scaled. \code{size} can be a character string of dimensions in length by
height format such as \code{"720x480"} or an abbreviated standard such as
\code{"ntsc"}. See
\href{http://ffmpeg.org/ffmpeg-utils.html#Video-size}{FFmpegstandard video
sizes} for common dimensions and available abbreviations.
Presets provide a certain encoding speed to compression
ratio. Available presets include \code{ultrafast},
\code{superfast}, \code{veryfast}, \code{faster}, \code{fast},
\code{medium}, \code{slow}, \code{slower}, \code{veryslow}.
Faster preset i.e.(\code{ultrafast}) corresponds to greater file
size, lower animation quality, and faster computation
times. Slower speeds \code{veryslow} corresponds to smaller
file, higher quality animation and slower computation times.
See \url{http://trac.ffmpeg.org/wiki/Encode/H.264}
@details \code{codec} is ignored if the file name in
\code{pattern} ends with \code{.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 \code{codec="h264"},
\code{"libx264"}, \code{"libvpx"}, \code{"prores"},
\code{"qtrle"}, etc., but the user needs to be knowledgeable
regarding which codecs can be used for which output types or
errors will be thrown.
\code{format} is ignored if the file name in
\code{pattern} ends with \code{.gif}. The default is
\code{"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 \code{system("ffmpeg -pix_fmts")}.
\code{lossless} is ignored except for relevant
\code{codec} settings, e.g., \code{h264} or \code{libx264}. If
\code{TRUE}, recommended \code{preset} values are
\code{ultrafast} or \code{veryslow}. See
\url{https://trac.ffmpeg.org/wiki/Encode/H.264} for more
information.
}
\examples{
\dontrun{
# 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")
}
}
\author{
Todd Hayden, Tom Binder, Chris Holbrook
}
\keyword{internal}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment