The Code4Lib Journal – Video Playback Modifications for a DSpace Repository
Mission
Editorial Committee
Process and Structure
Code4Lib
Issue 31, 2016-01-28
Video Playback Modifications for a DSpace Repository
This paper focuses on modifications to an institutional repository system using the open source DSpace software to support playback of digital videos embedded within item pages. The changes were made in response to the formation and quick startup of an event capture group within the library that was charged with creating and editing video recordings of library events and speakers.
This paper specifically discusses the selection of video formats, changes to the visual theme of the repository to allow embedded playback and captioning support, and modifications and bug fixes to the file downloading subsystem to enable skip-ahead playback of videos via byte-range requests.
This paper also describes workflows for transcoding videos in the required formats, creating captions, and depositing videos into the repository.
by Keith Gilbertson and Liz McVoy
Motivation
VTechWorks is the institutional repository of the University Libraries of Virginia Tech, which launched in late 2011 using the DSpace software. At launch, the plan for VTechWorks was for it to act as a general-purpose repository for digital collections at the library, including theses and dissertations, scholarly articles, historical images and digital scans of cookbooks from the special collections department, and digitized materials from the archives. During the mass import of legacy content, it was noticed that several digital video files had entered into the collection, including promotional videos for the cooperative extension office and tribute videos that were sent to Virginia Tech after the campus mass shooting tragedy of April 16, 2007.
We had interesting video content in the repository, but the initial use cases for DSpace institutional repositories focused primarily on textual content: for example, collections of journal article pre-prints in PDF format. DSpace has been described as largely format agnostic, in that it allows users to deposit any type of file and to make these various file types available for download, if not in-browser display. However, the repository group at Virginia Tech thought that it would be fun to allow playback of videos from within the item page. Also, popular video streaming sites such as YouTube have conditioned users to expect embedded video playback in the web browser, instead of clicking on a video filename to download it first. Thus, video playback in DSpace was quickly hacked together, and the initial release of the video playback project in VTechWorks happened in August of 2012. Closed caption and subtitle support was added in November of 2012, in anticipation of future needs. The service was advertised in internal (but public) blog postings (Video playback …, 2012; VTechWorks Closed Caption …, 2012), with a few sample videos converted to the required formats.
By advertising the capability on a blog posting and listing the format requirements, the hope was that others would continue to submit video content to VTechWorks. There was collaboration with computer science students for a class project to record computer science seminars, but outside of this successful project, few new videos were submitted to VTechWorks.
Then, in 2013, the library event capture group was formed. The event capture group provides, free of charge, video recording services for scholarly events up to two hours in length (Event Capture, 2015). From the time of its formation, this group has deposited videos of over one hundred events to VTechWorks, with more pending.
Functionality
The project allows for playback of digital videos within a viewer embedded in the item pages of VTechWorks. The customized software detects whether an item has videos encoded in the necessary formats, and if so, renders an HTML5 video player within the web browser. If the web browser does not support HTML5 video, then a fallback option using the Adobe Flash player is presented.
Our implementation of this project uses the video.js (Video.js Player, 2015) player to customize the embedded HTML5 video player and to present the Flash fallback option in the theme. With theme changes, the project is also compatible with alternative players, such as Flowplayer, or can be made to rely entirely on the built-in controls for video playback in HTML5 capable web browsers. The system supports the use of a “Movie Poster”, an image file that is displayed in the embedded viewer before playback is requested. This can be a still from an interesting frame of the video, or a title frame for the video, and is meant to avoid display of a blank canvas in the video playback area.
Playback support is intended to work on popular browsers on popular operating systems, including Firefox, Internet Explorer, Chrome, and Opera on OS X, Windows, and Linux, and on mobile devices based on Android and iOS operating systems. Some basic requirements of video playback are supported; for example, the video playback can begin even as just the beginning of the file has been downloaded, and the viewer can skip ahead to view parts of the video that have not yet been downloaded. These features are especially important for mobile devices, which may have limited storage space.
If a WebVTT file is present in the item, the file is used to provide text indexing of the video for the search discovery system, and to present subtitles on screen.
Selection of Video Formats
After the event capture group became involved and began producing videos frequently, more thought was put into standardizing the video formats for ease of processing. In this project, the video formats can be conceived of as three types.
The original format, as captured by the camera
The preservation format, an archival copy that can used to create other formats
Presentation formats, used for display in the web browser
The preservation format was selected after research by the video event capture group at the time of the initial implementation. Members were Liz McVoy, Scott Pennington, and Therese Walters. The event capture group produces the preservation copy after the video has been edited. The specification is as follows:
Preservation Format:
Multimedia container file: .mov
Video Codec: ProRes 422
Resolution: 1920×1080
The presentation formats were selected based on the capability of web browsers at the time of the original implementation, and based on experimentation. Browser support for HTML5 video has improved greatly, but there are still differences between browsers and platforms. An updated chart of HTML5 compatible multimedia formats on both mobile and desktop is on the Mozilla Developer Network. Some web browsers, such as Safari on OS X and iOS, natively supported mp4 files with h264 encoding, while other browsers, such as Chrome, supported webm files with VP8 encoding. Therefore, each video has two presentation files stored in VTechWorks, an mp4 file and a webm file.
Presentation Format, .mp4:
Multimedia container file: .mp4
Video Codec: h264 video, two-pass encoding
Resolution: 854×480 target ( do not scale up if the original is smaller)
Audio: AAC
Pixel format: yuv420p
Moov atom: Located at front of file
Bitrate: 1200 kbps variable
Presentation Format, .webm:
Multimedia container file: .webm
Video Codec: vp8
Resolution: 854×480 target ( do not scale up if the original is smaller)
Audio: Ogg Vorbis
Pixel format: yuv420p
Bitrate: 1200 kbps variable
There are some peculiarities to these specifications. The pixel format of “yuv420p” was selected for compatibility with Google Chrome for Windows. When the videos were encoded with other pixel formats, they did not play back on Chrome in Windows. Our specification for the .mp4 file states that the moov atom should be located at the beginning of the file. The moov atom serves as a time-based index to the rest of the file. If the moov atom is not located at the beginning of the file, then skip-ahead functionality is not enabled, and in some cases the video will not play at all. (Placing moov atom … , 2010)
If an mp4 file and a webm file are both present in an item, the video playback features will be enabled in the theme. In addition to the video files, it is possible to include other files to support optional features in the playback functionality. Image files support thumbnails and movie posters; webvtt files support subtitles.
Thumbnail:
File format: .jpg
File naming convention: video_filename.mp4.jpg, video_filename.webm.jpg
Size: 100 pixels, maximum width
Location: THUMBNAIL bundle in VTechWorks
Movie Poster:
File format: .jpg
File naming convention: video_filename.jpg
Size: Same dimensions as 1 video frame (target 854×480)
Location: MOVIEPOSTER bundle in VTechWorks
DSpace organizes bitstreams, or files, into logical groups called bundles. Typical bundles in a DSpace repository include ORIGINAL, THUMBNAIL, and LICENSE. The MOVIEPOSTER bundle is a special bundle that was added for this project.
Subtitles:
File format: .webvtt, specification at http://dev.w3.org/html5/webvtt/
Location: ORIGINAL bundle in VTechWorks
With the current implementation, the video playback functionality will only detect and use one webvtt file for each item. Due to this limitation, it is not currently possible to display subtitles in an alternate language, for example.
Code Changes
Overview
The code changes that were necessary to support this feature modified several subsystems of DSpace, including the file download system, web theming, and configuration of indexing and file types. Code additions are stored in the VTUL (Virginia Tech University Libraries) group GitHub repository.
File type Registry
DSpace utilizes a file format registry that lists file types known to DSpace. Registry entries for the mp4, webm, and WebVTT file formats were added to the registry, bitstream-formats.xml.
video/mp4MP4 ContainerMP4 Container format for video files0falsem4vmp4video/webmwebm videoThe webm video container format0falsewebmtext/vttWebVTT caption fileClosed caption or subtitle file for HTML5 video1falsevtt
These entries in the file type registry allow the theme to detect the presence of these files and to customize its view accordingly. The xml file shown here will configure file entries for new DSpace installations. For previously installed repositories, there is a web interface to add new format entries.
Theming
VTechWorks uses the XMLUI user interface for DSpace 5.4. This interface uses XSLT to transform XML representations of DSpace objects and metadata into HTML for display in a web browser. The XMLUI allows themes to customize views for the entire repository, or for individual collections. The current theme for VTechWorks is a lightly customized version of a theme created with responsive design principles, called “Mirage2”, from the @mire company. The main customization to the Mirage2 theme for this project is a modification to the item view page that displays an embedded video playback area when the user is looking at video items. There are also changes to include and style the video.js plugin.
First, the page-structure.xsl file was modified to include the necessary css and Javascript files for the video.js tool.
http://vjs.zencdn.net/c/video-js.css
The page links to the files on the video.js project server, instead of linking to copies that could be stored on the VTechWorks server. This potentially introduces performance issues, or instability when the files are modified. However, it also allows VTechWorks to automatically and effortlessly benefit from the latest improvements to the video.js project.
The item-view.xsl file checks for the existence of an mp4 and a webm file, and if and only if both exist, displays the video playback area in the item view page. If a webvtt file is provided for subtitles, or an image file for use as a movie poster, these are also detected and handled. The code uses the standard HTML5 video, source, and track elements. Video.js detects these elements and customizes them accordingly.
The theme is not able to detect if the moov atom is located at the front of the mp4 file, as is required per proper operation. The site superuser.com has suggestions about how to detect the location of the moov atom from scripts. Also, all videos are given a viewport of the same dimensions, regardless of their aspect ratio. In our current revision, this size is set to 854×480, which matches the dimensions of our current presentation formats in VTechWorks, and is a 16/9 aspect ratio.
BitstreamReader
In DSpace repositories using the XMLUI interface, there is a Java class called the BitstreamReader that is responsible for reading deposited files from storage and sending the files back to the requesting web browser. The BitstreamReader class at one time contained byte range support that enabled downloading of arbitrary portions of files. In the stock DSpace distribution, this code had been commented out because it was reported to cause problems with some downloads, in particular with some external PDF viewers.
Changes to the BitstreamReader.java file include enabling these byte range downloads again, and fixing bugs related to arithmetic and HTTP headers.
HTTP byte range offsets start with 0; this led to an off-by-one error that was corrected:
/* entityRange = byteRange.intersection(
new ByteRange(0, this.bitstreamSize)).toString(); */
// this code fixes off by 1 error in commented line above
requestedRange = byteRange.intersection(
new ByteRange(0, this.bitstreamSize - 1));
entityRange = requestedRange.toString();
It was also discovered that the Content-Length HTTP header was missing, and that the word “bytes” was absent from the Content-Range header.
//response.setHeader("Content-Range", entityRange + "/" + entityLength);
// V.T. fix for headers
response.setHeader("Content-Length",""
+ requestedRange.length());
response.setHeader("Content-Range",
”bytes " + entityRange + "/" + entityLength);
Properly functioning byte range downloads are necessary to enable viewers to skip ahead to a portion of the video that has not yet been downloaded, and for allowing playback on mobile devices, which typically have little storage space. After these problems were corrected, mobile device playback and the skip-ahead feature functioned properly.
At the time of publication of this article, another problem was discovered with byte range downloads. See the “Problems” section for more details.
Transcoding scripts
During the earliest stages of experimentation, videos were encoded on an individual basis as the embedded playback feature was tested on different file types. After the event capture group was started, videos were added to the repository more often. The preservation video format had been standardized, and it was an appropriate time to attempt automation for transcoding to the presentation formats.
The event capture group was created at a time when system administrator availability was difficult to come by in the library. A Mac mini and several external drives were purchased to act as a makeshift file server. A perl script was hacked together (Garbage Scripts, 2015) to create the mp4 and webm presentation files from the preservation copy, along with the thumbnails and movie poster file. The “-movflags faststart” option is used to make sure that the moov atom is placed at the beginning of the file.
This script was retired at the same time as the makeshift file server was retired and moved to a production appropriate system, and video transcoding is now handled with iffmpeg, a closed-source, commercial GUI front-end for the ffmpeg encoder that runs on OS X.
The iffmpeg program meets all of our technical needs and is more flexible, but due to a shortage of available staff time, there is now a demand for the script to be returned to service. This is more challenging than expected because of the need to find an available server node with large storage capabilities and high compute capability.
Configuration
The DSpace configuration file, dspace.cfg, has an entry that lists bundle names that appear in the web interface for item uploads.
xmlui.bundle.upload = ORIGINAL, METADATA, THUMBNAIL, MOVIEPOSTER, LICENSE, CC-LICENSE
The modified line shown here adds the MOVIEPOSTER bundle so that the Movie Poster files can be uploaded from the web interface.
DSpace has a set of media filters that process common file types such as images, to build thumbnails, and PDF files, for full text indexing. Even though WebVTT is not an HTML file, we can configure the HTMLFilter to provide full text indexing of the subtitles:
filter.org.dspace.app.mediafilter.HTMLFilter.inputFormats = HTML, Text, text/vtt
Testing
The very first item to serve as a test for video in VTechWorks is a tribute video that was presented to Virginia Tech.
Figure 1. Screenshot of Embedded Tribute Video
The video playback functionality was tested on the most popular platforms, including Android and iOS, and Safari, Chrome, Firefox, and Opera on OS X, and Firefox, Chrome, and Internet Explorer 6, 8, and 9 on Windows.
Multiple versions of Internet Explorer were tested, because the HTML5