Package 'editry'

editry

Description

R bindings to the editly NodeJS, for declarative video editing https://github.com/mifi/editly/.

---

Add the path to ffmpeg to the system path

Description

If ffmpeg can already be seen by the system, the system path will not be changed. Otherwise, the system path will be prepended with the ffmpeg path.

Usage

er_add_ffmpeg_path()

Value

TRUE on success, invisibly

---

Audio track

Description

The difference between er_audio_track and er_layer_audio() is that an er_audio_track will continue to play across multiple clips and can start and stop whenever needed.

Usage

er_audio_track(path, cut_from, cut_to, start, mix_volume)

Arguments

path	string: path to audio file
cut_from	numeric: time value to cut from, in seconds
cut_to	numeric: time value to cut to, in seconds
start	numeric: how many seconds into the video should this audio track start? (default = 0)
mix_volume	numeric: relative volume when mixing this video's audio track with others (default = 1)

Value

A list of class er_audio_track

References

https://github.com/mifi/editly/

See Also

er_header(), er_spec()

---

Execute editly in docker image

Description

Does not require node or editly to be installed on your system, instead requires that Docker is running and that you have pulled a suitable editly docker image. By default this is scienceuntangled/editly, which uses a modified version of editly. Other editly docker images can be used, but will not support the ⁠logo_*⁠ parameters in er_header or er_spec.

Usage

er_exec_docker(
  spec,
  docker_image = "scienceuntangled/editly",
  fast = FALSE,
  extra_docker_args
)

Arguments

spec	er_spec: an er_spec object as returned by er_spec()
docker_image	string: name of the docker image to use
fast	logical: if TRUE, run editly in 'fast' (low quality/preview) mode
extra_docker_args	character: additional arguments to pass to the docker command, e.g. extra_docker_args = c("--cpu-shares", "512") will limit the docker containiner's CPU priority when CPU cycles are limited (see https://docs.docker.com/config/containers/resource_constraints/)

Value

0 for success (invisibly)

References

https://github.com/mifi/editly/

Examples

## Not run: 
  clips <- list(er_clip_title2(duration = 3, text = "Title slide"),
                er_clip_image(duration = 3, path = "https://jeroen.github.io/images/Rlogo.png"))
  outfile <- tempfile(fileext = ".mp4")
  my_spec <- er_spec(clips = clips , out_path = outfile, allow_remote_requests = TRUE)
  er_exec_docker(my_spec)
  if (interactive()) browseURL(outfile)

## End(Not run)

---

Execute editly

Description

Execute editly

Usage

er_exec_wait(spec, fast = FALSE, ...)

Arguments

spec	er_spec or string: er_spec object, or a string giving the path to a JSON file or a JSON string, as returned by er_spec()
fast	logical: if TRUE, run editly in 'fast' (low quality/preview) mode
...	: if a JSON file is not being used, you can provide command line arguments as individual parameters

Value

0 for success (invisibly)

References

https://github.com/mifi/editly/

Examples

## Not run: 
  clips <- list(er_clip_title2(duration = 3, text = "Title slide"),
                er_clip_image(duration = 3, path = "https://jeroen.github.io/images/Rlogo.png"))
  outfile <- tempfile(fileext = ".mp4")
  my_spec <- er_spec(clips = clips , out_path = outfile, allow_remote_requests = TRUE)
  er_exec_wait(my_spec)
  if (interactive()) browseURL(outfile)

## End(Not run)

---

Path to the ffmpeg executable

Description

Path to the ffmpeg executable

Usage

er_ffmpeg_exe()

Value

The path to the executable, or NULL if not found

See Also

er_install_ffmpeg()

Examples

er_ffmpeg_exe()

---

Install the editly node package

Description

Editry requires that editly (the underlying nodeJS package) be available on your system, along with node and ffmpeg. These can either be installed directly on your system, or in a docker image. er_install_editly will attempt to install node, ffmpeg, and editly directly on your system. See the package overview at https://scienceuntangled.github.io/editry for docker-based installation.

Usage

er_install_editly(force = FALSE, dependencies = TRUE)

Arguments

force	logical: if TRUE, force reinstallation of editly if it is already installed
dependencies	logical: if TRUE, the system binaries node (via noder::nr_install_node()) and ffmpeg (via er_install_ffmpeg()) will also be installed if not found on your system

Value

The path to the installation (invisibly)

References

https://github.com/scienceuntangled/editly/

---

Install ffmpeg

Description

This is a helper function to install ffmpeg. Currently it only works on Windows and Linux platforms. The ffmpeg bundle will be downloaded from https://github.com/BtbN/FFmpeg-Builds/releases/latest (Windows) or https://johnvansickle.com/ffmpeg/ (Linux) and saved to your user appdata directory.

Usage

er_install_ffmpeg(force = FALSE, bits, check_hash = TRUE)

Arguments

force	logical: force reinstallation if ffmpeg already exists
bits	integer: 32 or 64, for 32- or 64-bit install. If missing or NULL, will be guessed based on .Machine$sizeof.pointer. Note that only 64-bit is supported on Windows
check_hash	logical: don't check the hash of the downloaded file. Ignored on windows

Value

the path to the installed executable

References

https://github.com/BtbN/FFmpeg-Builds/releases/latest https://johnvansickle.com/ffmpeg/

Examples

## Not run: 
  er_install_ffmpeg()

## End(Not run)

---

Create various sections of an editly spec

Description

Create various sections of an editly spec

Usage

er_layer(type, ...)

er_clip(duration, transition, layers)

er_defaults(transition, layer, layer_type)

er_header(
  out_path = tempfile(fileext = ".mp4"),
  fps,
  width,
  height,
  allow_remote_requests,
  audio_file_path,
  loop_audio,
  keep_source_audio,
  clips_audio_volume,
  output_volume,
  audio_norm.enable,
  audio_norm.gauss_size,
  audio_norm.max_gain,
  defaults,
  custom_output_args,
  logo_path,
  logo_width,
  logo_height,
  logo_x,
  logo_y
)

Arguments

type	string: the layer type (e.g. "title", "image", "video")
...	: other parameters
duration	numeric: duration in seconds
transition	list: an er_transition() object
layers	list: a list of er_layer objects
layer	list: default layer spec
layer_type	list: default layerType spec
out_path	string: the path of the video file to create (the file extension can be a video file extension or ".gif")
fps	numeric: frames per second (default = 25 or FPS of first video)
width	integer: video width (default = 640)
height	integer: auto based on width and aspect ratio of first video
allow_remote_requests	logical: allow remote URLs as paths? (default = FALSE)
audio_file_path	string: set an audio track for the whole video
loop_audio	logical: loop the audio track if it is shorter than video? (default = FALSE)
keep_source_audio	logical: keep source audio from clips? (default = FALSE)
clips_audio_volume	numeric: volume of audio from clips relative to er_audio_track()s (default = 1)
output_volume	numeric or string: adjust output volume (final stage). e.g. 0.5 or "10dB" (default = 1)
audio_norm.enable	logical: enable audio normalization? (default = FALSE)
audio_norm.gauss_size	numeric: audio normalization gauss size (default = 5)
audio_norm.max_gain	numeric: audio normalization max gain (default = 30)
defaults	er_defaults: as returned by er_defaults()
custom_output_args	character: vector of custom output codec/format arguments for ffmpeg
logo_path	string: path to logo file. This must be a local file, even if allow_remote_requests is TRUE. logo_path will be ignored if out_path is a gif
logo_width	numeric: width of logo relative to screen width (0 to 1, default = 0.2). If only one of logo height or width is specified, the logo aspect ratio will be retained
logo_height	numeric: height of logo relative to screen width (0 to 1, default = 0.1). If only one of logo height or width is specified, the logo aspect ratio will be retained
logo_x	numeric: logo left-hand-edge position relative to left of screen (0 = left to 1 = right, default = 0.78). The logo is referenced relative to its left-hand edge, so the default of 0.78 and width 0.2 puts the right-hand edge at 0.98
logo_y	numeric: logo bottom-edge position relative to top of screen (0 = top to 1 = bottom, default = 0.98)

Value

A list with class er_clip, er_layer, etc

References

https://github.com/mifi/editly/

See Also

er_spec()

---

Standard layer types

Description

position can be one of either:

• top, bottom center, top-left, top-right, center-left, center-right, bottom-left, bottom-right

• a list object x, y, originX = 'left', originY = 'top' , where x: 0, y: 0 is the upper left corner of the screen, and x: 1, y: 1 is the lower right corner, x is relative to video width, y to video height. originX and originY are optional, and specify the position's origin (anchor position) of the object.

Usage

er_layer_pause(color)

er_layer_image(path, resize_mode, zoom_direction, zoom_amount)

er_layer_image_overlay(
  path,
  position,
  width,
  height,
  zoom_direction,
  zoom_amount
)

er_layer_title(
  text,
  font_path,
  text_color,
  position,
  zoom_direction,
  zoom_amount
)

er_layer_subtitle(text, font_path, text_color)

er_layer_title_background(text, font_path, text_color, background)

er_layer_news_title(
  text,
  font_path,
  font_size,
  text_color,
  background_color,
  position
)

er_layer_slide_in_text(
  text,
  font_path,
  font_size,
  char_spacing,
  color,
  position
)

er_layer_fill_color(color)

er_layer_radial_gradient(colors)

er_layer_linear_gradient(colors)

er_layer_rainbow_colors()

er_layer_video(
  path,
  resize_mode,
  cut_from,
  cut_to,
  width,
  height,
  left,
  top,
  origin_x,
  origin_y,
  mix_volume
)

er_layer_audio(path, cut_from, cut_to, mix_volume)

er_layer_detached_audio(path, cut_from, cut_to, start, mix_volume)

Arguments

color	string: slide color (default = random)
path	string: path to image or video file
resize_mode	: see Details
zoom_direction	string: "in", out", or "null" to disable
zoom_amount	numeric: amount to zoom (default = 0.1)
position	string or list: see Details
width	numeric: width (from 0 to 1) where 1 is screen width
height	numeric: height (from 0 to 1) where 1 is screen height
text	string: text to show
font_path	string: path to font
text_color	string: text color
background	er_layer: as returned by er_layer_radial_gradient(), er_layer_linear_gradient(), or er_layer_fill_color()
font_size	numeric: font size
background_color	string: background color
char_spacing	numeric: character spacing
colors	character: vector of two colors (default = random)
cut_from	numeric: time value to cut from, in seconds
cut_to	numeric: time value to cut to, in seconds
left	numeric: X-position relative to screen width (0 to 1, default = 0)
top	numeric: Y-position relative to screen height (0 to 1, default = 0)
origin_x	numeric: X anchor ("left" or "right", default = "left")
origin_y	numeric: Y anchor ("top" or "bottom", default = "top")
mix_volume	numeric: relative volume when mixing this video's audio track with others (default = 1)
start	numeric: how many seconds into this clip should this audio track start? (default = 0)

Details

Audio layers will be mixed together. If cutFrom/cutTo is set, the resulting segment (cutTo-cutFrom) will be slowed/sped-up to fit clip.duration. The slow down/speed-up operation is limited to values between 0.5x and 100x. er_layer_detached_audio is a special case of audio_tracks that makes it easier to start the audio relative to clips start times without having to calculate global start times. detached audio has the exact same properties as audio_tracks, except start time is relative to the clip's start.

For video layers, if parent clip.duration is specified, the video will be slowed/sped-up to match clip.duration. If cutFrom/cutTo is set, the resulting segment (cutTo-cutFrom) will be slowed/sped-up to fit clip.duration. If the layer has audio, it will be kept (and mixed with other audio layers if present.)

resize_mode - How to fit image to screen. Can be one of:

• "contain" - All the video will be contained within the frame and letterboxed

• "contain-blur" - Like contain, but with a blurred copy as the letterbox

• "cover" - Video be cropped to cover the whole screen (aspect ratio preserved)

• "stretch" - Video will be stretched to cover the whole screen (aspect ratio ignored). Default is "contain-blur".

Value

A list with class er_layer

References

https://github.com/mifi/editly/

See Also

er_layer()

---

Create a spec ready for compiling to video

Description

Create a spec ready for compiling to video

Usage

er_spec(
  header,
  clips,
  audio_tracks,
  theme = "er_theme_default",
  as = "object",
  ...
)

Arguments

header	er_header: as returned by er_header(). Alternatively, do not specify the header argument but pass named header parameters separately
clips	list: a list of er_clip objects as returned by er_clip()
audio_tracks	list: a list of er_audio_track objects, as returned by er_audio_track()
theme	string: name of a theme function to apply, or NULL for no theme. The theme will set defaults, but will not override any defaults specified in the header
as	string: either "object" (return an object of class er_spec, suitable to pass to er_to_json(), or "json" (the JSON string as obtained from er_to_json())
...	: as for er_header

Value

A list of class er_spec or a JSON string

References

https://github.com/mifi/editly/

See Also

er_layer(), er_to_json(), er_exec_wait()

---

Default editry theme

Description

Themes in editry are a set of defaults that can be supplied to the er_header() or er_spec() functions.

Usage

er_theme_default()

Details

The default theme currently uses:

• white text, with 'PatuaOne' font face

• black slide backgrounds for plain slides, and grey gradients for radial or linear gradient backgrounds

• red background for news-title layers

• resize_mode "contain" for images

Value

An object of class er_defaults

See Also

er_defaults(), er_spec()

---

Convert editly spec to JSON string

Description

Convert editly spec to JSON string

Usage

er_to_json(spec)

Arguments

spec	string: a JSON string as returned by er_spec()

Value

A JSON string

---

Clip transitions

Description

A clip transitions is the outgoing transition from the clip.

Usage

er_transition(name, duration, audio_out_curve, audio_in_curve)

Arguments

name	string: can be any of the transitions listed in https://gl-transitions.com/gallery, or "directional-left", "directional-right", "directional-up", "directional-down", "random", " dummy"
duration	numeric: duration in seconds
audio_out_curve	string: fade out curve in audio cross fades (default = "tri")
audio_in_curve	string: fade in curve in audio cross fades (default = "tri")

Value

A list with class er_transition

References

https://github.com/mifi/editly/

See Also

er_clip()

---