recalbox.conf

Introduction

The recalbox has an advanced configuration tool named recalbox.conf that allows you to modify some options not available in emulationstation.

You can edit the file by either :

  • The webmanager (the easiest way). The webmanager can be reached as follows:

    Windows: http://recalbox/ or enter the IP address.

    Linux/Mac: http://recalbox.local/ or enter the IP address.

    Now go on the left side to recalbox.conf

  • Using the network shared folders on the recalbox. The file is available in a directory named system that contains recalbox.conf

  • You can [[connect as root|Root-access-on-terminal-(EN)]] and edit the file on the system at /recalbox/share/system/recalbox.conf

For Windows users : If you dont use the option via the webmanager, you must use a real text editor software program, like NotePad++. The default windows text editor inserts bad characters in the file.

The ; at line start means the line is disabled. Remove the ; to enable the line.

I - Available options

  • A - System Options

    • set system power switch option

    • set splash screen duration

    • enable / disable fbcp (framebuffer for TFT screens on gpio/spi)

    • enable / disable recalbox-manager auto start

    • set recalbox-manager version

    • enable / disable security

    • set emulationstation video mode

    • set menu style for emulationstation

    • set emulationstation boot/display options

    • set emulators special keys

    • hide kodi in emulationstation

    • start kodi on system startup

    • avoid x button to start kodi

    • set kodi video mode

    • set kodi network delay

  • B - Network

    • set hostname

    • set wifi ssid and key

    • set up to 3 different wifi networks (system will use the first that works)

    • enable / disable samba

    • enable / disable virtual-gamepads

    • enable / disable ssh

  • C - Audio

    • set output device

    • set audio volume

    • enable / disable background music in es

  • D - Controllers

    • enable bluetooth controllers

    • enable steam controllers

    • select ps3 driver

    • enable / disable controllers on gpio

    • enable / disable controllers on marqs DB9

    • enable / disable controllers on marqs gamecon

    • enable / disable controllers xarcade

  • F - Language and keyboard

    • set language

    • set keyboard layout

    • set time zone

  • G - UPDATES

    • enable / disable update checking

    • set update type

  • H - EMULATOR CONFIGURATION - detailed below

  • **I - EMULATORS CHOICES

  • J - NETPLAY CONFIGURATION

II - Emulator configuration

1 - Global configuration

You can fine tune emulators in recalbox.conf. The global variable set the preferences for all emulators.

Available variables :

  • videomode : set videomode (use tvservice to get compatible values). Use default to disable videomode switch (for crt)

    example : global.videomode=CEA 4 HDMI

  • shaderset : set the shader set for all emulators (none, retro, scanlines) see [[shaders configuration|Shaders-configuration-(EN)]]

    example : global.shaderset=retro

  • integerscale : enable integerscale "pixel perfect" in games

    example : global.integerscale=0

  • shaders : set the absolute path to the shader or shader preset (glsl or glslp)

    example : global.shaders=/recalbox/share_init/shaders/scanline.glslp

  • ratio : set the ratio for games (16/9, 4/3, 16/10, auto or custom)

    example : global.ratio=16/9

  • smooth : smooth games

    example : global.smooth=0

  • rewind : enable rewind in games (can slow down emulators)

    example : global.rewind=1

  • autosave : enable autosave/load in games during game's exit/start

    example : global.autosave=0

  • retroachievements : enable retroachievements in games

    example : global.retroachievements=0

  • retroachievements hardcore mode : enable retroachievements hardcore mode in games (disable rewind and savestates)

    example : global.retroachievements.hardcore=0

  • retroachievements username : set your retroachievements username

    example : global.retroachievements.username=

  • retroachievements password : set your retroachievements password

    example : global.retroachievements.password=

  • inputdriver : force input drivers for retroarch (auto, sdl2, udev)

    example : global.inputdriver=auto

The default configuration :

global.videomode=CEA 4 HDMI
global.shaderset=none
global.integerscale=0
global.shaders=
global.ratio=auto
global.smooth=1
global.rewind=1
global.autosave=0
global.retroachievements=0
global.retroachievements.hardcore=0
global.retroachievements.username=
global.retroachievements.password=
global.inputdriver=auto

If you want to enable smoothing for all emulators, set global.smooth=1. If you want to add a scanline shader for all emulators, set global.shaders=/recalbox/share_init/shaders/scanline.glslp.

2 - Specific emulator configuration

Each emulator can be configured here. Just use the name of the system and set variables.

Available systems :

snes , nes , n64 , gba , gb , gbc , fds , gamecube , wii , virtualboy , sg1000 , mastersystem , megadrive , gamegear , sega32x , segacd , dreamcast , neogeo , mame , fba , fba_libretro , ngp , ngpc , gw , vectrex , lynx , lutro , wswan , wswanc , pcengine , pcenginecd , supergrafx , atari2600 , atari7800 , atarist , apple2 , amstradcpc , c64 , colecovision , msx , msx1 , msx2 , dos , scummvm , o2em , zxspectrum , zx81 , prboom , cavestory , psx , psp , moonlight

Available libretro cores :

  • snes : pocketsnes - snes9x_next - catsfc - snes9x

  • nes / fds : fceumm - fceunext - nestopia

  • n64 : mupen64plus - glupen64

  • gamecube / wii : dolphin

  • gb / gbc : gambatte - tgbdual

  • gba : gpsp - mgba - meteor

  • virtualboy : vb

  • megadrive / mastersystem / gamegear / sega32x / segacd / sg1000 : genesisplusgx - picodrive

  • dreamcast : reicast

  • neogeo : imame4all - mame2003 - mame2010 - fbneo

  • neogeo CD : fbneo

  • mame : imame4all - mame2003 - mame2010

  • fba_libretro : fbneo

  • ngp / ngpc : mednafen_ngp

  • gw : gw

  • vectrex : vecx

  • lynx : handy - mednafen_lynx

  • lutro : lutro

  • wswan / wswanc : mednafen_wswan

  • pcengine / pcenginecd /supergrafx : mednafen_supergrafx - pce

  • atari2600 : stella

  • atari7800 : prosystem

  • atarist : hatari

  • c64 : vice

  • amstradcpc : cap32

  • apple2 : lineapple

  • zx81 : zx81

  • zxspectrum : fuse

  • o2em : o2em

  • colecovision : bluemsx

  • dos : dosbox

  • scummvm : scummvm

  • msx / msx1 / msx2: bluemsx - fmsx

  • prboom : prboom

  • psx : pcsx_rearmed - mednafen_psx

  • psp : ppsspp

  • cavestory : nxengine

  • moonlight : moonlight

  • naomi : flycast

  • Intellvision : freeintv

  • pc98 : np2kai

  • pc88 : quasi88

  • x68000 : px68k

  • x1 : x1

​

Available variables :

  • videomode : set videomode (use tvservice to get compatible values).

    example : snes.videomode=CEA 4 HDMI

  • integerscale : enable integerscale "pixel perfect" in games.

    example : snes.integerscale=0

  • shaders : set the absolute path to the shader or shader preset (glsl or glslp).

    example : snes.shaders=/recalbox/share_init/shaders/scanline.glslp

  • ratio : set the ratio for games (16/9, 4/3, auto_or _custom)

    example : snes.ratio=4/3

  • smooth : smooth games

    example : snes.smooth=0

  • rewind : enable rewind in games (can slow down emulators)

    example : snes.rewind=1

  • autosave : enable autosave/load in games during game's exit/start

    example : snes.autosave=0

  • core : select the core for the emulation (libretrocores are located in /usr/lib/libretro)

    example : snes.core=snes9x_next

  • emulator : select the emulator for the emulation (emulators are retroarch, fba2x, mupen64)

    example : neogeo.emulator=fba2x

  • configfile : force your own configuration file to be loaded. The recalbox will not automatize emulator configuration

    example : snes.configfile=/path/to/my/configfile.cfg

​

III - The default recalbox.conf for rpi3Variable

# System Variable
# You can configure your recalbox from here
# To set a variable, remove the first ; on the line
​
​
​
# ------------ A - System Options ----------- #
# Uncomment the system.power.switch you use
;system.power.switch=ATX_RASPI_R2_6 # http://lowpowerlab.com/atxraspi/#installation
;system.power.switch=MAUSBERRY # http://mausberry-circuits.myshopify.com/pages/setup
;system.power.switch=REMOTEPIBOARD_2003 # http://www.msldigital.com/pages/support-for-remotepi-board-2013
;system.power.switch=REMOTEPIBOARD_2005 # http://www.msldigital.com/pages/support-for-remotepi-board-plus-2015
;system.power.switch=WITTYPI # http://www.uugear.com/witty-pi-realtime-clock-power-management-for-raspberry-pi
;system.power.switch=PIN56ONOFF # https://github.com/recalbox/recalbox-os/wiki/Add-a-start-stop-button-to-your-recalbox-(EN)
;system.power.switch=PIN56PUSH # https://github.com/recalbox/recalbox-os/wiki/Add-a-start-stop-button-to-your-recalbox-(EN)
;system.power.switch=PIN356ONOFFRESET # https://github.com/recalbox/recalbox-os/wiki/Add-a-start-stop-button-to-your-recalbox-(EN)
;system.power.switch=PIN356PUSHRESET # https://github.com/recalbox/recalbox-os/wiki/Add-a-start-stop-button-to-your-recalbox-(EN)
​
## fbcp FrameBuffer Copy Program
## For small TFT screen on GPIO and SPI
## See https://github.com/recalbox/recalbox-os/wiki/Utility---Use-of-fbcp-for-small-TFT-screen-%28EN%29 for details
## Needed for Waveshare 3.2" 3.5" TFT screen, 2.8" Adafruit screen
## See https://github.com/recalbox/recalbox-os/wiki/TFT-Screen-SPI-Bus-%28EN%29
## for support and configuration details needed by /boot/config.txt
system.fbcp.enabled=0
​
## Splash screen duration
## 0: Video will be played for 20 seconds (default)
## -1: All the video will be played (it won't be stopped automatically)
## >0 : Time before the video will be stopped (in seconds)
system.splash.length=0
​
## Recalbox Manager (http manager)
system.manager.enabled=1
## Currently, only version 2 is available
system.manager.version=2
​
## Recalbox security
# enforce security
# samba password required
# disable virtual gamepads
system.security.enabled=0
​
## Recalbox API (REST)
system.api.enabled=0
​
## Allow a specific resolution for ES only from the command : tvservice -m [MODE]
## Leave commented for the default usual behaviour
;system.es.videomode=CEA 4 HDMI
​
## EmulationStation
### menu style
### default -> default all options menu
### none -> no menu except the game search menu
### bartop -> less menu, only needed for bartops
emulationstation.menu=default
### Select a system to show on boot (use rom directory name) (string)
emulationstation.selectedsystem=favorites
### Show the gamelist of the first or selected system on boot (0,1)
emulationstation.bootongamelist=0
### Disable system view. ES will boot and show ONLY the first or selected system (0,1)
emulationstation.hidesystemview=0
### Parse Gamelists only. Show only games listed in gamelist.xml files (0,1)
emulationstation.gamelistonly=0
### Force basicgameList view to be displayed, even if your game systems are scraped (0,1)
emulationstation.forcebasicgamelistview=0
​
## Scrapers
### ScreenScraper.fr
### Force media region - if not defined, region is taken from system.language. Default: us
;scraper.screenscraper.region=eu
### Force text language - if not defined, region is taken from system.language. Default: en
;scraper.screenscraper.language=fr
### Choose the media to download among:
### screenshot: game screenshot
### title : game title screenshot
### box2d : Front case
### box3d : 3D rendered case
### mixv1 : Recalbox special mix image V1 (default)
### mixv2 : Recalbox special mix image V2
;scraper.screenscraper.media=mixv1
### ScreenScraper account
;scraper.screenscraper.user=
;scraper.screenscraper.password=
​
## Emulator special keys
## default -> default all special keys
## nomenu -> cannot popup the emulator menu
## none -> no special keys in emulators
system.emulators.specialkeys=default
​
## Show or hide kodi in emulationstation (0,1)
kodi.enabled=1
## Start kodi at launch (0,1)
kodi.atstartup=0
## set x button shortcut (0,1)
kodi.xbutton=1
​
## Allow a specific resolution for Kodi only from the command : tvservice -m [MODE]
## By default is using the default resolution of your screen
kodi.videomode=default
​
## Kodi can wait for a network component before starting
## waithost is the ip or hostname that must answer to a ping to validate the availability
## waittime is the maximum time waited when kodi boots
## if waitmode is required, kodi will not start if the component is not available
## if waitmode is wish, kodi will start if the component is not available
## if waitmode is not set or has another value, kodi will start immediately
;kodi.network.waitmode=required
;kodi.network.waittime=10
;kodi.network.waithost=192.168.0.50
​
## Hyperion
## Hyperion allows you to use an ambilight like led system on your recalbox
## Use hypercon to create your configuration file, and copy it in /recalbox/share/system/configs/hyperion/hyperion.config.json
hyperion.enabled=0
​
​
# ------------ B - Network ------------ #
## Set system hostname
system.hostname=RECALBOX
## Activate wifi (0,1)
wifi.enabled=0
## Set wifi region
## More info here: https://github.com/recalbox/recalbox-os/wiki/Wifi-country-code-(EN)
wifi.region=US
## Wifi SSID (string)
;wifi.ssid=new ssid
## Wifi KEY (string)
## after rebooting the recalbox, the "new key" is replace by a hidden value "enc:xxxxx"
## you can edit the "enc:xxxxx" value to replace by a clear value, it will be updated again at the following reboot
## Escape your special chars (# ; $) with a backslash : $ => \$
;wifi.key=new key
​
## Wifi - static IP
## if you want a static IP address, you must set all 3 values (ip, gateway, and netmask)
## if any value is missing or all lines are commented out, it will fall back to the
## default of DHCP
;wifi.ip=manual ip address
;wifi.gateway=new gateway
;wifi.netmask=new netmask
​
# secondary wifi (not configurable via the user interface)
;wifi2.ssid=new ssid
;wifi2.key=new key
# defaults to dhcp. uncomment for static ip
;wifi2.ip=manual ip address
;wifi2.gateway=new gateway
;wifi2.netmask=new netmask
​
# third wifi (not configurable via the user interface)
;wifi3.ssid=new ssid
;wifi3.key=new key
# defaults to dhcp. uncomment for static ip
;wifi3.ip=manual ip address
;wifi3.gateway=new gateway
;wifi3.netmask=new netmask
​
## Samba share
system.samba.enabled=1
### Virtual Gamepads
system.virtual-gamepads.enabled=1
### SSH
system.ssh.enabled=1
​
# ------------ C - Audio ------------ #
## Set the audio device (auto, hdmi, jack)
audio.device=auto
## Set system volume (0..100)
audio.volume=90
## Enable or disable system sounds in ES (0,1)
audio.bgmusic=1
​
​
​
# -------------- D - Controllers ----------------- #
# Enable support for standard bluetooth controllers
controllers.bluetooth.enabled=1
​
​
## Please enable only one of these
# -------------- D1 - PS3 Controllers ------------ #
##Enable PS3 controllers support
controllers.ps3.enabled=1
## Choose a driver between bluez, official and shanwan
## bluez -> bluez 5 + kernel drivers, support official and shanwan sisaxis
## official -> sixad drivers, support official and gasia sisaxis
## shanwan -> shanwan drivers, support official and shanwan sisaxis
controllers.ps3.driver=bluez
​
​
# ------------ D2 - GPIO Controllers ------------ #
## GPIO Controllers
## enable controllers on GPIO with mk_arcarde_joystick_rpi (0,1)
controllers.gpio.enabled=0
## mk_gpio arguments, map=1 for one controller, map=1,2 for 2 (map=1,map=1,2)
controllers.gpio.args=map=1,2
## Custom mk_gpio arguments,
## map=5 gpio1=Y-,Y+,X-,X+,start,select,a,b,tr,y,x,tl,hk for one controller,
## map=5 gpio1=pin1,pin2,pin3,.....,pin12,pin13
## map=5,6 gpio1=Y-,Y+,X-,X+,start,select,a,b,tr,y,x,tl,hk gpio2=Y-,Y+,X-,X+,start,select,a,b,tr,y,x,tl,hk for 2 (map=5,map=5,6)
## map=5,6 gpio1=gpiox,gpioy,gpioz,.....,gpiou,gpiov gpio2=gpiox,gpioy,gpioz,.....,gpiou,gpiov
# where gpiox,gpioy,gpioz ... are NOT pin numbers on the connector, BUT location gpio numbered as in
# https://www.raspberrypi-spy.co.uk/wp-content/uploads/2012/06/Raspberry-Pi-GPIO-Layout-Model-B-Plus-rotated-2700x900.png
## Set pin to -1 to disable it
# controllers.gpio.args=map=5,6 gpio=4,17,27,22,10,9,25,24,23,18,15,14,2 gpio2=11,5,6,13,19,26,21,20,16,12,7,8,3
## MCP configuration : GPIO and MCP can be used together. You can mix them.
## map=0x20,0x21 for 2 mcp23017 on i2c bus
#controllers.gpio.args=map=0x20,0x21,5,6 gpio=4,17,27,22,10,9,25,24,23,18,15,14,-1 gpio2=11,5,6,13,19,26,21,20,16,12,7,8,-1
​
​
​
# ------------ D3 - Steam Controllers ------------ #
## Enable steam controller service
controllers.steam.enabled=0
​
​
## DB9 Controllers
## Enable DB9 drivers for atari, megadrive, amiga controllers (0,1)
controllers.db9.enabled=0
## db9 arguments
controllers.db9.args=map=1
​
## Gamecon controllers
## Enable gamecon controllers, for nes, snes, psx (0,1)
controllers.gamecon.enabled=0
## gamecon_args
controllers.gamecon.args=map=1
​
## XGaming's XArcade Tankstik and other compatible devices
controllers.xarcade.enabled=1
​
​
​
# ------------ F - Language and keyboard ------------ #
## Set the language of the system (fr_FR,en_US,en_GB,de_DE,pt_BR,es_ES,it_IT,eu_ES,tr_TR,zh_CN)
system.language=en_US
## set the keyboard layout (fr,en,de,us,es)
;system.kblayout=us
## Set you local time
## Select your timezone from : ls /usr/share/zoneinfo/ (string)
;system.timezone=Europe/Paris
​
​
​
# ------------ G - UPDATES ------------ #
## Automatically check for updates at start (0,1)
updates.enabled=1
# Update type : default to stable
updates.type=stable
​
​
# ------------ H - HERE IT IS - GLOBAL EMULATOR CONFIGURATION ------------ #
## The global value will be used for all emulators, except if the value
## is redefined in the emulator
​
## Set game resolution for emulators
## select your mode from the command : tvservice -m [MODE]
## CEA 5 HDMI : 1920x1080 @ 60Hz 16:9, clock:74MHz interlaced
## CEA 4 HDMI : 1280x720 @ 60Hz 16:9, clock:74MHz progressive
## use 'default' for using the default resolution
## use 'auto' : switches to CEA 4 HDMI if supported, else keep the current resolution
## (string)
global.videomode=CEA 4 HDMI
​
## Shader set
## Automatically select shaders for all systems
## (none, retro, scanlines)
global.shaderset=none
​
## Once enabled, your screen will be cropped, and you will have a pixel perfect image (0,1)
global.integerscale=0
​
## Set gpslp shader for all emulators (prefer shadersets above). Absolute path (string)
global.shaders=
​
## Set ratio for all emulators (auto,4/3,16/9,16/10,custom)
global.ratio=auto
​
## Set smooth for all emulators (0,1)
global.smooth=1
​
## Set rewind for all emulators (0,1)
global.rewind=1
​
## Set autosave/load savestate for all emulators (0,1)
global.autosave=0
​
## Enable retroarchievements (0,1)
## Set your www.retroachievements.org username/password
## Escape your special chars (# ; $) with a backslash : $ => \$
global.retroachievements=0
global.retroachievements.hardcore=0
global.retroachievements.username=
global.retroachievements.password=
​
## Set retroarch input driver (auto, udev, sdl2)
## If you don't have issues with your controllers, let auto
global.inputdriver=auto
​
## If you do not want recalboxOS to generate the configuration for all emulators (string)
;global.configfile=/path/to/my/configfile.cfg
​
## Demo screensaver parameters
## Set the system list from which ES will run random games.
## Empty list or unexisting key means all available systems
global.demo.systemlist=3do,amigacd32,atari2600,atari5200,atari7800,daphne,fba_libretro,fds,gamegear,gba,lynx,mame,mastersystem,megadrive,neogeo,nes,ngpc,pcengine,sega32x,sg1000,snes
## Default demo game sessions last 90s. Change this value if you want shorter or longer sessions
;global.demo.duration=90
## Default game info screen duration lasts 6s. Change this value if you want shorter or longer info screens.
;global.demo.infoscreenduration=6
​
## Retroarch AI Translation service
## Comment out or set to 0 the following key if you don't want the AI service
global.translate=1
## Set the source and the target languages.
## Allowed language list: EN, ES, FR, IT, DE, JP, NL, CS, DA, SV, HR, KO, ZH_CN, ZH_TW, CA, BG, BN, EU, AZ, AR, SQ,
## AF, EO, ET, TL, FI, GL, KA, EL, GU, HT, IW, HI, HU, IS, ID, GA, KN, LA, LV, LT, MK, MS,
## MT, NO, FA, PL, PT, RO, RU, SR, SK, SL, SW, TA, TE, TH, TR, UK, UR, VI, CY, YI
## Setting the translate.from key to a specified language may speed up or give more accurate results
## If translate.to key is commented, the default value is extracted from system.language or, if system.language is
## undefined, set to auto (=EN).
global.translate.from=auto
global.translate.to=auto
## zTranslate API Key
## go to https://ztranslate.net and create an account.
## validate your account, then log in and go to the settngs page
## Look for the API Key at the bottom of the page, then uncomment the following key and paste your API Key:
;global.translate.apikey=YOUR_API_KEY_HERE
## Other translation service
## If you want to use another translation service or a custom API call, use this key to
## specify the url to call. If the key is not empty, it is used instead of zTranslation's API Key
;global.translate.url=
​
## Arcade metasystem
## Activate the Arcade metasystem to group all games from piFBA, FBN (libretro), MAME and optionally Neogeo
## into a single "Arcade" system.
;global.arcade=1
## You may want to specify its position in the system list. (Default: 0)
## Negatives values may be used to tart from the end (-1 = last position)
;global.arcade.position=0
## Include NeoGeo or not (default: 1)
;global.arcade.includeneogeo=1
## Hide included system or leave them in the system list (default: 1)
;global.arcade.hideoriginals=1
​
​
# ------------ I - EMULATORS CHOICES ----------- #
## You can override the global configurations here
## Here is the snes example
;snes.videomode=CEA 4 HDMI
;snes.core=snes9x2010
;snes.shaders=/recalbox/share/shaders/shaders_glsl/mysnesshader.gplsp
;snes.ratio=16/9
;snes.smooth=0
;snes.rewind=1
;snes.autosave=0
;snes.emulator=libretro
;snes.integerscale=0
## If you do not want recalboxOS to generate the configuration for the emulator:
;snes.configfile=/path/to/my/configfile.cfg
​
## Default cores for RPi3
snes.core=snes9x2010
​
## NeoGeo emulator
## You can use pifba or a libretro core (fba2x,libretro)
neogeo.emulator=libretro
## If you set libretro as neogeo.emulator, the line below sets the retroarch core (fbneo, mame2000)
neogeo.core=fbneo
​
## N64 emulator is configured to display a screen with a 640x480 resolution (native n64 resolution)
## So you must use one of these video modes (DMT 4 HDMI,CEA 1 HDMI).
## If your screen is not compatible with one of these video modes, please check the recalbox's wiki.
n64.videomode=DMT 4 HDMI
## If you are using a CRT screen, please change the setting above with this one :
# n64.videomode=default
​
## Dreamcast emulator
## Like N64, such a CPU intensive emulator needs a small resolution
## Consider DMT 4 HDMI (640*480) or DMT 9 HDMI (800*600). If you have a black screen on dreamcast, try DMT 9 HDMI here
dreamcast.videomode=DMT 4 HDMI
​
## Demo screensaver parameters
## Include or exclude a particular system from the demo screensaver
## You may change the global.demo.systemlist key or include/exclude every single system
;snes.demo.include=0
## Set the session duration for a particular system
;snes.demo.duration=90
​
# ------------ J - NETPLAY PARAMETERS ----------- #
## All these values are handled by Recalbox itself
global.netplay=1
global.netplay.nickname=
global.netplay.port=55435
global.netplay.relay=
global.netplay.systems=fba_libretro,mame,mastersystem,megadrive,neogeo,nes,pcengine,sega32x,sg1000,snes,supergrafx
global.netplay.lobby=http://lobby.libretro.com/list/
​
## Configurations generated by Recalbox
​