Capturing Footage in Real-Time Without Additional Hardware from RetroPie’s Libretro Core Emulators
The following guide demonstrates how to enable the capture of real-time gameplay footage from various console systems available in the RetroPie emulator suite, a number of which can utilise the RetroArch framework to provide an integrated audio-video recording facility.
Implemented natively on a standard Raspberry Pi, this approach runs without the need for any external hardware (such as an Elgato capture-card).
- A Little Background Information
- A Note Before Proceeding
- Installing FFmpeg and Selected Codecs
- Rebuilding RetroArch to Enable FFmpeg Recording
- Checking FFmpeg has Been Enabled in RetroArch
- Activating the RetroArch Recording Features
- Performance Enhancements
- Streaming to Twitch
- Related Posts
- External Links
A Little Background Information
My motivation to undertake what has become a sizeable research, development, and experimentation, project grew from a simple desire to obtain recordings of emulators running under RetroPie. I’d previously managed to enable the audio-video feature provided by the Atari ST emulator, Hatari, and was hopeful that a software-only solution was feasible for other systems.
At time of writing this guide has been tested on RetroPie 3.7, 3.8.1, and 4 (rc-1) setups, all running on installations of Raspbian Jessie 2016-05-27, and RetroPie 4.0.3 installed on Raspbian Jessie with Pixel 2016-09-23
Searching for other emulators offering recording, I found only the non-Libretro variant of Fuse to have in-built facilities; whilst serviceable for capturing ZX Spectrum games, the audio-video files generated by the emulator are of a decidedly non-standard format.
Fundamentally it was my experiments when attempting to transcode footage of Technician Ted captured from Fuse, first with avconv, and later with FFmpeg, and a subsequent enquiry on the RetroPie forum, which spawned the series of articles which form this how-to guide.
For reference, the system used whilst researching this project was a Raspberry Pi 3, overclocked to 1300mhz (please see Overclocking the Raspberry Pi 3: Thermal Limits and Optimising for Single vs Multicore Performance for specifics).
I strongly advise that a full backup be made of the system, as there is no simple method to reverse the actions of the compilation and installation processes described below.
A full image of the Raspberry Pi‘s SD Card can be made using a tool such as Win32DiskImager
Installing FFmpeg and Selected Codecs
The FFmpeg audio-video suite is the key component required to facilitate in-game recording; unfortunately the Raspbian operating system which underpins RetroPie does not come with this collection of tools and codecs pre-installed.
As defined by the project’s Wikipedia page: FFmpeg is a free software project that produces libraries and programs for handling multimedia data.
Obtaining required software on Raspbian is often as simple as using the
apt command, specifying the appropriate package to acquire; at time of writing, however, this option cannot be used as neither FFmpeg, nor several required codecs, are available in the repository.
The solution is to obtain the source code and build these components directly; for an all-in-one script which performs this task, and a full description of the process for those interested, please see my guide: Compiling Software from Source Code on the Raspberry Pi: The FFmpeg Suite
Rebuilding RetroArch to Enable FFmpeg Recording
Please see the my earlier post: What is RetroPie? for a little background on RetroPie, RetroArch, and Libretro.
At time of writing, the version of the RetroArch framework implemented by RetroPie specifically excludes the in-built recording facility which utilises FFmpeg, however this feature can be implemented with relative ease.
Please Note: the process listed in this section obtains and builds the latest, not necessarily stable, RetroArch source from GitHub. Should you encounter issues, the solution is to build a specific known-good release of RetroArch. I shall be updating this guide in due course, but for the time being please see the revised instructions in the comments for this post (search this page for “OBTAIN AND BUILD SPECIFIC VERSION OF RETROARCH TO ENABLE FFMPEG RECORDING”).
As explained by RetroPie forum administrator BuZz in the thread containing my initial question regarding in-game recording:
“Assuming you are comfortable in the terminal:
Install your ffmpeg headers etc, then”
cd ~/RetroPie-Setup/ # remove the config that disables ffmpeg on the RPI sed -i "s/--disable-ffmpeg//" scriptmodules/emulators/retroarch.sh # build new retroarch from source sudo ./retropie_packages.sh retroarch # put the file back how it was git checkout scriptmodules/emulators/retroarch.sh
These commands can be executed line-by-line from a terminal; alternatively, should you wish to run the code as a single script:
Create a new text file in nano with an appropriate name and an extension of
Denote the file as a bash script by entering the first line as:
- Copy and paste the code block into the file, then save it.
Make the file executable using the
- Run the script from the command line.
The above code selects the
RetroPie-Setup directory, then modifies the
retroarch.sh script to remove the parameter which disables the recording subsystem. Next the
retropie_packages.sh script is called to fetch, compile, and install RetroArch. Finally a standard version of the
retroarch.sh script is retrieved from RetroPie’s github repository.
Given that acquisition, compilation, and installation of FFmpeg is a prerequisite for this process, I’ll not repeat instructions regarding use of the bash command line, the nano text editor, setting permissions, and related tasks. Please refer to Compiling FFmpeg and Codecs from Source Code: All-in-One Script for an illustrated example of creating and executing a script.
It is possible that the
retroarch.sh script which is modified at the start of this process may be out of date with respect to the RetroArch source code which is subsequently fetched and built. If in doubt, to avoid issues one option would be to update RetroPie prior to running this code; another approach is to perform this procedure on a fresh installation.
If FFmpeg is not present on the system when RetroArch is built after removing the
--disable-ffmpeg switch, or has not been compiled utilising static rather than shared libraries, there will be no warnings or errors, but RetroArch will not contain the recording features.
Checking FFmpeg Has Been Enabled in RetroArch
Once FFmpeg has been compiled and installed, and RetroArch has been rebuilt, it’s worth confirming that the recording facility has been incorporated. This is a simple check as the RetroArch menu (a.k.a RGUI) will contain additional entries if the process has been successful.
In RetroPie 3.x by default a controller which has been setup via Emulation Station will automatically have several hotkey combinations mapped, including
x to access the RetroArch menu. For further details please see the RetroArch Configuration page on the RetroPie wiki.
Alternatively, with a USB or Bluetooth keyboard connected the RetroArch menu can be accessed via the
The changes visible in the GUI menu depend upon the RetroArch version installed, as shown by the number in the buttom-left of the screen.
For RetroArch 1.3.4 or earlier only, after the RGUI menu has loaded, enter the Settings sub menu, and confirm that a new entry for Recording is now present:
In RetroArch 1.3.6. this Recording menu will not be present. This may be explained by the fact that despite RetroArch 1.3.4 containing a Recording menu, it’s not possible to use the options within to directly start and stop the process whilst an emulator is running, nor modify settings including the file name and location, use of a configuration file, or recording of filtered output.
For RetroArch 1.3.4 and 1.3.6, within the Settings menu, select the Driver sub menu. The option for Record Driver should now read
ffmpeg rather than
null. This confirms that RetroArch recognises and has enabled the FFmpeg suite.
Please note: there does not appear to have been a full 1.3.5 RetroArch release, hence the jump from 1.3.4 to 1.3.6.
Activating the RetroArch Recording Features
At this stage the RetroArch framework has been rebuilt to expose the native FFmpeg-based features, and we can take a final couple of steps to allow recording to commence.
Activation of recording unfortunately cannot be undertaken from within the RetroArch GUI menu, and instead requires that parameters be added to the commands that launch a given emulator; this is achieved via an
emulators.cfg configuration file. RetroPie provides a separate config per system, located within
/opt/retropie/configs, which contains a series of directories named per machine, rather than per emulator.
An Overview of the Emulators.cfg File
This section provides background information regarding the content of the
emulators.cfg file, its role in launching an emulator, and connection to the runcommand menu. Feel free to skip ahead to the next section for details on modifying a configuration file to add recording options.
The entries in the
emulators.cfg file play a dual role, both providing the commands to launch an emulator, and being used to display the options in the runcommand “Select Default Emulator” and “Select Emulator for Rom” sub-menus.
The runcommand menu is accessed by pressing any key on the keyboard, or the button mapped as
A on a controller, when launching a game from Emulation Station. For details see the RetroPie wiki Runcommand page.
As an example, below is the configuration file for the the Atari VCS emulator, Stella, located at
lr-stella="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/stella_libretro.so --config /opt/retropie/configs/atari2600/retroarch.cfg %ROM%" default="lr-stella" stella="stella -maxres 320x240 %ROM%"
emulators.cfg file consists of name / value pairs, in the form:
parameter = "value". A configuration file can comprise multiple items, which generally allow the selection of different emulators for the same system, as is the case with the N64, Megadrive, and SNES.
The name of the actual Atari 2600 emulator is Stella; as is the convention, the Libretro / RetroArch core version is named with a
Multiple entries also enable a single emulator to be launched with varying configurations; for example the Atari ST emulator Hatari offers ‘fast’ and ‘compatible’ options, both with and without border display.
In the above example the first line specifies an entry named “lr-stella” (emphasised in bold for clarity), which is the Libretro core version of the Stella emulator. The value for this item consists of the commands used to launch the emulator within the RetroArch framework, loading the rom selected via Emulation Station.
A list of systems and their corresponding emulators can be found on the RetroPie wiki Supported Systems page.
The name “lr-stella” also appears on the second line as the value for the parameter named “default”; this specifies the entry to use when launching any rom for which an emulator has not been explicitly set (via the “Select emulator for rom” sub-menu).
On the final line appears an entry for the non-Libretro core version of the VCS emulator; the name of the executable,
stella, appears first, followed by a command line parameter to set the resolution, followed by a variable,
%ROM%, representing the selected game to run.
Within the Runcommand “Choose Default Emulator” menu, these
emulators.cfg entries appear as follows:
Adding Recording Options to the RetroPie Runcommand Menu
As described in the preceeding section, the
emulators.cfg file contains one or more entries which ultimately launch a game selected via Emulation Station within a given emulator.
Using the Atari 2600 as an example, the original entry for the Libretro emulator in the file
lr-stella="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/stella_libretro.so --config /opt/retropie/configs/atari2600/retroarch.cfg %ROM%"
The format of the runcommand entry is as follows:
- Name of entry as it will appear in the runcommand menu (e.g. “lr-stella”)
- Path and filename of the RetroArch executable
-L, used to specify a Libretro core.
- Path and filename of the Libretro core shared library.
--config, used to specify an emulator-specific configuration file
- Path and filename of the Libretro of the RetroArch emulator-specific configuration file
To activate the FFmpeg recording features, we need to insert an additional parameter, providing the path and filename for the recording output file.
As it’s unlikely that you’ll always want to run the emulator with recording activated, you will probably want to make a copy the original Libretro emulator entry, modifying the name and adding the paramater; the runcommand menu can then be used to quickly choose between recording and non-recording versions of the Libretro emulator.
- First copy the entire “lr-stella=” entry, pasting it back into the file below the original.
- Update the name of the new entry as “lr-stella-record-hdd-noconfig” to make it easily identifiable within the runcommand menu.
Immediately after the filename of the Libretro emulator core shared library file (
stella_libretro.so), insert a space and add the
--recordparameter, followed by another space.
Finally, add the full path and filename of the audio-video output file to create:
The entire new line appears as follows:
lr-stella-record-hdd-noconfig="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/stella_libretro.so --record /media/pi/EXT_HDD/RPi_AVI/recording_VCS.mkv --config /opt/retropie/configs/atari2600/retroarch.cfg %ROM%"
N.b: I’m directing output to an external hard disk for performance reasons. Please see the section Recording to an External Storage Device, below, for details.
Simply adding the
--record parameter is sufficient to activate the recording feature once the emulator is launched, however this causes RetroArch to utilise default FFmpeg parameters which will allow only the least demanding emulators to run at full speed.
All is not lost, however, as we can provide a configuration file to specify custom values allowing real-time recording at 60 FPS even with demanding systems such as the lr-pcsx_reamred PlayStation emulator.
Recording with the Custom RecordConfig Option
Creation and customisation of a
recordconfig configuration file is discussed in detail in the Performance Enhancements section, below.
In anticipation, we can add an item to the runcommand entries in the previously modified
emulators.cfg to specify the location and name of the FFmpeg configuration file.
- First copy the entire “lr-stella-record-hdd-noconfig=” entry, pasting it back into the file below the original.
- Update the name of the new item as “lr-stella-record-hdd” to distinguish it from the existing entries.
Immediately after the path and filename of the
--recordparameter, insert a space, then add the
--recordconfigparameter, followed by another space.
Finally, add the full path and filename of the recording configuration file:
The completed additional entry should appear as:
lr-stella-record-hdd="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/stella_libretro.so --record /media/pi/EXT_HDD/RPi_AVI/recording_VCS.mkv --recordconfig /home/pi/RetroPie/recording/config/config.cfg --config /opt/retropie/configs/atari2600/retroarch.cfg %ROM%"
The final, updated version of the Stella
emulators.cfg file is as follows:
lr-stella="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/stella_libretro.so --config /opt/retropie/configs/atari2600/retroarch.cfg %ROM%" lr-stella-record-hdd-noconfig="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/stella_libretro.so --record /media/pi/EXT_HDD/RPi_AVI/recording_VCS.mkv --config /opt/retropie/configs/atari2600/retroarch.cfg %ROM%" lr-stella-record-hdd="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/stella_libretro.so --record /media/pi/EXT_HDD/RPi_AVI/recording_VCS.mkv --recordconfig /home/pi/RetroPie/recording/config/config.cfg --config /opt/retropie/configs/atari2600/retroarch.cfg %ROM%" default="lr-stella-record-hdd" stella="stella -maxres 320x240 %ROM%"
Following the addition of entries to the
emulators.cfg file, the runcommand menu will appear as follows:
Unfortunately it is necessary to repeat the above steps for each Libretro core emulator for which recording is required, as RetroPie maintains a separate
emulators.cfg per system; it is possible, however, to utilise a single recording configuration file, as demonstrated in the following section.
As the path and filename for the recording must be supplied via the
emulators.cfg file, each time the emulator is launched with the recording parameters any existing file will be overwritten. To partly offset this inconvenience I suffix the output file to identify the emulator; for the Atari 2600 I use
recording_VCS.mkv, for the PlayStation
If I’m making multiple recordings from the same emulator, the most efficient method to rename files is to remotely connect to the Raspberry Pi via ssh, changing the filename after exiting the emulator and returning to Emulation Station.
UPDATE: RetroPie forum member meleu suggested an improvement to avoid the inconvenience of renaming the file before each emulator launch, by automatically appending the filename with a timestamp (year-month-day-hourminutesecond), for example:
This is achieved by updating the
--record parameter as follows:
--record /media/pi/EXT_HDD/RPi_AVI/recording_VCS_$(date +%Y-%m-%d-%H%M%S).mkv
We can utilise two approaches to achieve real-time recording at a full 60FPS even when running demanding emulators such as lr-pcsx-rearmed (PlayStation).
Firstly, it is possible to fully customise the FFmpeg subsystem to minimise the recording overhead. Secondly, we can direct output to a fast external medium, such as a USB hard disk.
Both options, which are best applied in tandem, are demonstrated in the following sections.
Custom FFmpeg Recording Configuration
By supplying a configuration file it is possible to totally customise the FFmpeg subsystem to achieve far better recording performance (albeit whilst necessarily trading some quality for speed).
Without a configuration file, recording utilises the following FFmpeg settings, according to the RetroArch wiki:
“By default… lossless coding is used. This means libx264/RGB, with -qp 0… The audio codec used is FLAC. libx264/RGB ensures very nice bitrates even when lossless and very fast encoding.”
Real-time recording using these default settings is possible, but only on RetroArch emulators which do not overly tax the system, such as the Atari 2600.
I have determined that the equivalent configuration settings, as specified in a recordconfig file are as follows:
vcodec = libx264rgb
pix_fmt = bgr24
acodec = flac
format = matroska
video_qp = 0
The name and location of the file specified via the
--recordconfig parameter is entirely arbitrary, providing that the directories in the path exist and the file itself is accessible to the
pi user. I created a couple of subdirectories below the standard RetroPie user location:
As per the examples in the preceeding sections, I named my custom recording configuration file
config.cfg, and placed it within the new
/recording/config directory hierarchy.
In order to achieve real-time recording at a full 60fps (Ntfs) or 50fps (Pal) in emulators up to and including the PlayStation, I augmented the default FFmpeg configuration with settings to reduce the overhead of recording. The content of my
config.cfg is as follows:
format = matroska
threads = 3
vcodec = libx264rgb
video_preset = ultrafast
video_tune = animation
pix_fmt = bgr24
video_qp = 0
acodec = flac
Once the configuration file has been created with the above content, and saved to the location specified in the the emulators.cfg file as specified previously, launching the emulator with the appropriate runcommand entry should automatically begin generating a recording file.
Recording ends when the emulator is exited. Unfortunately it is not currently possible to start, stop, or otherwise alter the recording from within the RetroArch GUI menu.
Please note: When the PlayStation emulator is running with the enhanced graphics mode enabled, the recording outputs blank video in place of all 3D visuals.
Tuning the FFmpeg Recording Configuration
For those interested in further tuning the recording configuration file, the following analysis of the recording configuration file content may be of use:
threads = 3 allows FFmpeg to utilise three of the Pi Model 2 or Model 3‘s processor cores (leaving one for the single-core emulator itself).
video_preset = ultrafast is an x264 video codec specific preset, which itself incorporates a large number of configuration values which enable the encoder to consume far less resources, whilst maintaining a high quality output file.
video_tune = animation this setting fine-tunes the video compression for animation, which in common with retro-gaming graphics, tends to have large areas of static and similar-coloured output.
The permutations are nearly endless, and whilst I spent considerable time experimenting until I was able to achieve high-quality 60fps real-time recording with the PlayStation emulator, the configuration can doubtlessly be improved upon.
When tuning the settings, much depends on which codecs, and versions thereof, you incorporate into your FFmpeg build. Many settings are specific to the video and audio codec specified. The FFmpeg project site includes copious, very detailed documentation.
It appears that the values are parsed from the configuration file by RetroArch without any re-ordering; this is significant as they are used to directly drive the FFmpeg tool, which requires that parameters are passed in a specific order.
Mixing the parameters for one codec by passing them after specifying another invariably causes problems. Please see the FFmpeg documentation regarding parameter placement.
Recording to an External Storage Device
The overhead of recording whilst running an emulator is greatly reduced if the output is directed to an fast external storage device, such as a hard drive, rather than to the Pi‘s SD Card.
In tests, a standard USB 2 hard disk allows real-time recording at a full 60 FPS in emulators ranging from the relatively undemanding Atari 2600, through the Megadrive and SNES, and up to the comparatively complex PlayStation. I’ve not yet tested recording within the Libretro incarnation of the N64 emulator Mupen64plus.
In comparison, when directing output to a fast internally mounted SanDisk Class 10 48MB/s SD Card, the more demanding emulators suffered a noticeable drop in performance.
For details on mounting an external USB hard disk, at boot and within Emulation Station, please see my companion guide: Automatically Mounting an External USB Hard Disk on the Raspberry Pi
Where an emulator is launched via a
runcommand which directs recording output to an external storage device, in the event that the drive is not connected or not mapped to expected mount point, the emulator runs as normal; no errors or warnings will be displayed, and nothing will be reported in
Streaming to Twitch
Whilst I had planned to investigate and include information regarding using RetroArch’s FFmpeg facilities to live-stream from Libretro emulators to Twitch, circumstances have transpired which have precluded this. Perhaps at some point I shall return to this aspect of the project.
In the meantime there is a section on the RetroArch wiki covering FFmpeg Recording and Live Streaming which provides a sample
recordconfig file. It is likely that the custom config outlined earlier, combined with the stream-specific settings from the wiki example, will enable operation with Twitch.
The configuration file as it appears on the aforementioned site is as follows:
vcodec = libx264 acodec = libmp3lame pix_fmt = yuv420p scale_factor = 2 threads = 3 video_crf = 25 video_preset = superfast video_tune = animation audio_global_quality = 75 sample_rate = 44100 format = flv
The provided RetroArch recording parameter from the same site is:
--record rtmp://live.twitch.tv/app/$YOUR_TWITCH_ID --recordconfig twitch.cfg
A Labour of Love
- Links: Raspberry Pi and Gaming Emulation via RetroPie
- Compiling Software from Source Code on the Raspberry Pi: The FFmpeg Suite
- Automatically Mounting an External USB Hard Disk on the Raspberry Pi
- PlayStation Emulation on the Pi: Enhancing the Experience with the Options Menu – Part Two: Graphics
- Atari ST and STe Computing on the Raspberry Pi with RetroPie’s Hatari Emulator