Recording Live Gameplay in RetroPie’s RetroArch Emulators Natively on the Raspberry Pi

Capturing Footage in Real-Time Without Additional Hardware from RetroPie’s Libretro Core Emulators

Video Captured Natively in RetroPie - Source: RetroResolution

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

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.

RetroPie Versions Tested

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).

A Note Before Proceeding
System Backup

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.

What is FFmpeg?

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

What is RetroArch?

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/
# build new retroarch from source
sudo ./ retroarch
# put the file back how it was
git checkout scriptmodules/emulators/

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 .sh
  • 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 chmod command.
  • Run the script from the command line.

The above code selects the RetroPie-Setup directory, then modifies the script to remove the parameter which disables the recording subsystem. Next the script is called to fetch, compile, and install RetroArch. Finally a standard version of the script is retrieved from RetroPie’s github repository.

RetroArch Script in nano Editor - Build with FFmpeg Recording Enabled
RetroArch Script in nano Editor – Build with FFmpeg Recording Enabled

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 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.

Critical Note

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 select + 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 F1 key.

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:

RetroArch Menu - Settings Sub Menu - Recording Option
RetroArch Menu – Settings Sub Menu – Recording Option

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.

RetroArch Menu - Settings Sub Menu - Recording Sub Menu
RetroArch Menu – Settings Sub Menu – Recording Sub Menu

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.

RetroArch Menu - Settings Menu - Driver Sub Menu - Record Driver option
RetroArch Menu – Settings Menu – Driver Sub Menu – Record Driver option

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.

RetroArch 1.3.6 Menu - Settings Menu - Driver Sub Menu - Record Driver option
RetroArch 1.3.6 Menu – Settings Menu – Driver Sub Menu – Record Driver option

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.

RetroPie Runcommand Menu - Select Default Emulator Option
RetroPie Runcommand Menu – Select Default Emulator Option

As an example, below is the configuration file for the the Atari VCS emulator, Stella, located at /opt/retropie/configs/atari2600:

lr-stella="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/ --config /opt/retropie/configs/atari2600/retroarch.cfg %ROM%"
stella="stella -maxres 320x240 %ROM%"

The 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.

Emulator Naming Convention

The name of the actual Atari 2600 emulator is Stella; as is the convention, the Libretro / RetroArch core version is named with a lr- prefix.

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.

RetroPie Emulators

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:

RetroPie Runcommand Menu - Choose Default Emulator - Default
RetroPie Runcommand Menu – Choose Default Emulator – Stella

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 /opt/retropie/configs/atari2600/emulators.cfg is:

lr-stella="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/ --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
  • RetroArch parameter, -L, used to specify a Libretro core.
  • Path and filename of the Libretro core shared library.
  • RetroArch parameter, --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 (, insert a space and add the --record parameter, followed by another space.
  • Finally, add the full path and filename of the audio-video output file to create: /media/pi/EXT_HDD/RPi_AVI/recording_VCS.mkv

The entire new line appears as follows:

lr-stella-record-hdd-noconfig="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/ --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 --record parameter, insert a space, then add the --recordconfig parameter, followed by another space.
  • Finally, add the full path and filename of the recording configuration file: /home/pi/RetroPie/recording/config/config.cfg

The completed additional entry should appear as:

lr-stella-record-hdd="/opt/retropie/emulators/retroarch/bin/retroarch -L /opt/retropie/libretrocores/lr-stella/ --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/ --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/ --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/ --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%"
stella="stella -maxres 320x240 %ROM%"

Following the addition of entries to the emulators.cfg file, the runcommand menu will appear as follows:

RetroPie Runcommand Menu - Choose Default Emulator - Record No-Config Option
RetroPie Runcommand Menu – Choose Default Emulator – Record No-Config Option

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.

Naming the Recording File

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 recording_PSX.mkv, etc.

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

Performance Enhancements

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.

A Note Regarding the Order and Placement of Config Values

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

A Note Regarding Recording to an External Hard Disk

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 runcommand.log.

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://$YOUR_TWITCH_ID --recordconfig twitch.cfg

A Labour of Love

Retro Resolution is entirely a labour of love. Please consider offering a donation if the information here has helped illuminate, enlighten, or otherwise assisted you!
Donate Using PayPal

Privacy Policy
Terms and Conditions
© Retro Resolution


66 thoughts on “Recording Live Gameplay in RetroPie’s RetroArch Emulators Natively on the Raspberry Pi

  1. I compiled ffmpeg with omx support ti use hw h.264 encoder, is far away from x264, but very fast. Also why not to use utvideo?


      1. Thanks for the comments MasterBlatter.
        I did try the hardware encoder last July, but found the quality too poor to use; a that time ffmpeg support for it was very new, and none of the quality control options seemed to work.
        The other encoder is not one I’ve heard of; I don’t know if the Pi’s Video core IV chip has hardware support for it.
        Getting encoding to work at at was very difficult given the relative lack of horsepower available from the machine’s SoC!


      2. IIRC H264_omx doesn’t support quality crf or qp settings, but bitrate only and ffmpeg default is about 200kbps.
        Utvideo is a lossless codec tuned for speed, another one is ffv1, both sw only.
        I’ll try those in some days, and report here.


  2. thanks for your guide! i am getting recordings made but i can’t see any video afterwards–only audio is coming through. vlc says something like this:

    VLC media player 2.2.1 Terry Pratchett (Weatherwax) (revision 2.2.1~trusty2)
    [000000000141f118] core libvlc: Running vlc with the default interface. Use ‘cvlc’ to use vlc without interface.
    “sni-qt/6951” WARN 22:11:56.640 void StatusNotifierItemFactory::connectToSnw() Invalid interface to SNW_SERVICE
    [00007f650cc01808] mkv demux error: No tracks supported
    [00007f650cc01808] mkv demux error: No tracks supported
    [00007f650cc01808] mkv demux error: cannot find any cluster, damaged file ?

    any ideas? i don’t have any issue playing other videos


  3. Dont know what i´m doing wrong. When I add the –record option in the emulators.cfg, the emulator would not start.


    1. I’m glad the original article was useful, albeit outdated.
      Unfortunately ill health means that I’ve not been able to keep the guide updated. Many thanks for working on the changes to update this for the current releases.


Please Leave a Reply! Anonymous comments and 'markdown' formatting enabled.

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s