In mccarthy-m-g/embedr: Embed Multimedia Files in HTML Documents

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

If you need to embed multimedia files in an R Markdown document you must either:

Write raw HTML code in the body of your document.
Call an R function that handles the HTML code for you.

The embedr package uses the latter approach, making it fast and easy to embed audio or video in your R Markdown HTML documents:

By functionalizing the HTML <audio> and <video> elements, it makes your code more readable.
It provides error checking to ensure that your HTML code is correct and that your sources are valid.
It provides options to print placeholder text in R Markdown PDF documents so that you can distribute your document as HTML and PDF without creating separate functions or documents.

This document introduces you to embedr's embed_audio() and embed_media() functions, and shows you how to use them in R Markdown documents.

Setup

library(embedr)

Embed audio with `embed_audio()`

embed_audio() provides a standard way to embed audio in R Markdown documents when the output format is HTML, and to print placeholder text when the output format is not HTML. The first argument is the path or URL to the audio file. The remaining arguments allow you to specify the file type, audio player attributes, and placeholder text to be used when the output format is not HTML.

For example, we can embed .mp3, .ogg, or .wav files with:

audio_mp3 <- "https://michaelmccarthy.netlify.app/files/embedr/audio-vignette.mp3"
audio_ogg <- "https://michaelmccarthy.netlify.app/files/embedr/audio-vignette.ogg"
audio_wav <- "https://michaelmccarthy.netlify.app/files/embedr/audio-vignette.wav"
# embed .mp3 file
embed_audio(audio_mp3)
# embed .ogg file
embed_audio(audio_ogg, type = "ogg")
# embed .wav file
embed_audio(audio_wav, type = "wav")
# embed multiple file types (for use in different browsers)
embed_audio(c(audio_mp3, audio_ogg, audio_wav), type = c("mpeg", "ogg", "wav"))

And control the behaviour of the <audio> element with:

# embed looping .mp3 file
embed_audio(audio_mp3, attribute = c("controls", "loop"))

Placeholder text can be included in PDF versions of a document with:

placeholder_text <- paste0("If you are reading the PDF version of this ",
                           "vignette you will see this text instead of an ",
                           "audio player.")
# embed .mp3 file with placeholder text for the PDF version
embed_audio(audio_mp3, placeholder = placeholder_text)

Embed video with `embed_video()`

embed_video() provides a standard way to embed video in R Markdown documents when the output format is HTML, and to print placeholder text when the output format is not HTML. It shares most of its arguments with embed_audio(). Its unique arguments control the dimensions of the video player, and allow you to set a thumbnail for the video.

Control the video player's dimensions with:

video <- "https://michaelmccarthy.netlify.app/files/embedr/video-vignette.mp4"
# embed .mp4 video
embed_video(video, width = "256", height = "256")

Add a thumbnail with:

thumbnail <- "https://michaelmccarthy.netlify.app/files/embedr/thumbnail-vignette.png"
# embed .mp4 video
embed_video(video, width = "256", height = "256", thumbnail = thumbnail)