Skip to content

HD CRT Mode Switcher

Jump to bottom
NTG edited this page May 30, 2026 · 2 revisions

Caution

USE THIS TOOL AT YOUR OWN RISK. WE ARE NOT RESPONSIBLE FOR DAMAGE TO YOUR EQUIPMENT.

CRT MONITOR SAFETY:

  • A CRT MONITOR MUST NEVER BE TURNED ON DURING HD MODE!
  • HIGH FREQUENCIES DURING HD MODE CAN PERMANENTLY DAMAGE YOUR CRT MONITOR!
  • ONLY TURN ON YOUR CRT MONITOR WHEN IN CRT MODE AND AFTER BATOCERA HAS FULLY BOOTED.
  • KNOW YOUR GEAR.

What is the HD/CRT Mode Switcher?

The HD/CRT Mode Switcher is a feature that allows you to seamlessly switch between two display configurations

  • HD Mode: Standard Batocera configuration for modern displays (HDMI, DisplayPort, etc.)
  • CRT Mode: CRT Script configuration for 15/25/31kHz CRT monitors

Key Benefits

  • Seamless Switching: Toggle between HD and CRT modes with one menu selection and reboot
  • State Preservation: All configurations (emulator settings, video outputs, resolutions) are preserved and restored per mode
  • No Manual Reconfiguration: Eliminates the need to manually reconfigure settings when switching displays
  • Prevents Black Screens: Automatically handles video output selection to prevent display issues
  • Complete Isolation: HD and CRT configurations are completely separate—no mixing between modes

What Gets Switched?

The Mode Switcher manages:

  • Video Output: Automatically selects the correct display output for each mode
  • Video Resolution: Sets appropriate boot resolution (HD resolutions for HD Mode, CRT timings for CRT Mode)
  • Emulator Configurations: Complete folder swapping for MAME, RetroArch, and EmulationStation configs
  • System Files: Overlay file management (removed for vanilla Batocera in HD Mode, restored for CRT Mode)
  • Custom Binaries: CRT Script custom binaries are backed up/restored per mode
  • Scripts: CRT Script-specific scripts are preserved/removed per mode (user custom scripts always preserved)

Prerequisites

  1. Batocera v43+ installed and running
  2. CRT Script installed
  3. SSH access enabled on your Batocera system
  4. At least 2 video outputs connected - REQUIRED
  • A single port can be shared as both HD and CRT outputs but you will need a hardware switcher. Here's a Display Port one for example.
  1. Dual display setup (one HD display + one CRT monitor) - not required for handheld systems like Steam Deck since the handheld screen is the HD Display
    • Note: Even if you only have one physical display showing at a time, you still need 2 outputs configured
  2. Input device for navigating the Mode Switcher UI:
    • Keyboard - Arrow keys, Enter, Esc/Tab for navigation
    • Controller - Controller buttons are mapped to keyboard keys

Installation

The HD/CRT Mode Switcher is automatically installed when you run the Batocera v43 CRT Script installation. After installation completes and you reboot, the Mode Switcher will be available in EmulationStation's CRT tools menu.

Running the Mode Switcher

After installation, the Mode Switcher will be available in EmulationStation's CRT tools menu.

In EmulationStation, navigate to:

  • CRT TOOLS → HD/CRT Mode Switcher

Using the Mode Switcher

First Run Warning

On first launch, you'll see a critical safety warning about CRT monitor safety. Read it carefully and select "I UNDERSTAND" to proceed. This warning will not appear again after you acknowledge it.

Main Menu

The Mode Switcher will detect your current mode and show you the option to switch to the other mode:

  • If in CRT Mode: You'll see "Switch to HD Mode"
  • If in HD Mode: You'll see "Switch to CRT Mode"

Navigation:

  • Keyboard:
    • Use UP/DOWN arrow keys to navigate
    • Press Enter to select/confirm
    • Press Esc or Tab to cancel/go back
  • Controller:
    • Use UP/DOWN on D-pad or joystick to navigate
    • Press B button (mapped to Enter) to select/confirm
    • Press A button (mapped to Esc) to cancel

Step-by-Step Usage Flow

1. Video Output Selection

Note

You should already have CRT configs detected and set if this is the first time launching the app after initial CRT-Script install and boot. Launching this app for the first time should just ask Select an output for HD Mode.

The Mode Switcher will detect all available video outputs and ask you to select one for the target mode.

Understanding the Output Selection Dialog:

The dialog displays three columns of information for each detected output:

  • DETECTED OUTPUT: Lists the unique identifiers for video output ports that the system has detected. These are the names of the physical or logical display connectors available on your hardware.

    • Examples: DP-1 (DisplayPort 1), DP-2 (DisplayPort 2), HDMI-1 (HDMI 1), HDMI-2 (HDMI 2), DVI-I-1 (DVI-I 1), eDP-1 (embedded DisplayPort 1)

  • CONNECTED PORT: Indicates whether a display device is physically connected to the corresponding output port.

    • Status: connected (display/cable is plugged in) or disconnected (no display detected)

  • CURRENT OUTPUT: Shows the current operational status or assignment of the detected output.

    • [DISABLED] - Output is not currently configured for any mode
    • [CURRENT HD] - Output is currently configured for HD Mode
    • [CURRENT CRT] - Output is currently configured for CRT Mode
    • [SELECTED FOR HD] - Output has been selected for HD Mode (during current session)
    • [SELECTED FOR CRT] - Output has been selected for CRT Mode (during current session)

What to expect:

  • Outputs are marked with [CURRENT HD] or [CURRENT CRT] if they're already configured
  • Outputs are marked with [SELECTED FOR HD] or [SELECTED FOR CRT] if you've just selected them
  • The dialog shows connection status for each output
  • A RESCAN option is available to rescan outputs if you've connected/disconnected displays or changed cables

Important:

  • If you've already configured VIDEO OUTPUT and VIDEO MODE in ES MAIN MENU → SYSTEM SETTINGS, those settings will be respected and backed up
  • If VIDEO OUTPUT or VIDEO MODE are not configured, the Mode Switcher will force you to make those selections before allowing a mode switch
  • This prevents black screen issues while giving you full control
  • Ensure you select different outputs for HD Mode and CRT Mode - they cannot share the same output
  • If outputs have changed (cables connected/disconnected), use the RESCAN option to refresh the output list

Tip

Configuration from EmulationStation is always preserved and respected. If you've already set VIDEO OUTPUT and VIDEO MODE in System Settings, the Mode Switcher won't ask again.

2. Boot Resolution Selection (CRT Mode Only if not already set)

Note: This step will only appear if you have not configured VIDEO OUTPUT and VIDEO MODE in ES MAIN MENU → SYSTEM SETTINGS. If these are already configured, this step is skipped and your existing settings will be used.

Tip

Boot resolutions are pre-configured safe modes. Only resolutions prefixed with Boot_ are shown to ensure your CRT can display them safely during startup.

When switching to CRT Mode and VIDEO MODE is not configured, you'll be asked to select a boot resolution from your videomodes.conf file.

What to expect:

  • Only resolutions prefixed with Boot_ are shown (e.g., Boot_576i, Boot_480p)
  • These are safe resolutions that your CRT can display during boot
  • Select the resolution that matches your CRT's capabilities

Note: If switching to HD Mode, this step is skipped (HD Mode uses standard HD resolutions).

Note

During boot resolution selection, you're choosing the initial video mode before Batocera fully starts. Select a mode your CRT is known to support reliably.

3. Confirmation Dialog

You'll be asked to confirm the mode switch:

Are you sure you want to switch from [Current Mode] to [Target Mode]?

This will modify system files and require a reboot.
  • Select PROCEED to continue
  • Select CANCEL to abort

4. Safety Disclaimer

When switching TO CRT Mode:

IMPORTANT SAFETY WARNING

Before proceeding, you MUST:
1. DO NOT IMMEDIATELY TURN ON YOUR CRT
2. Keep your CRT Monitor off until after BIOS boot

WARNING:
High frequencies during PC BIOS boot could DAMAGE your monitor!

Only turn on your monitor AFTER Batocera has fully booted.

When switching TO HD Mode:

CRITICAL: CRT MONITOR SAFETY

Before proceeding, you MUST:
1. TURN OFF YOUR CRT IMMEDIATELY BEFORE RESET
2. Keep it OFF during the whole duration of HD Mode

WARNING:
High frequencies during PC BIOS boot and HD Mode could DAMAGE your monitor!

Only turn on your monitor AFTER CRT Mode has been initialized and AFTER Batocera has fully booted.

⚠️ READ THESE WARNINGS CAREFULLY ⚠️

Important

Safety warnings about CRT monitor power management are critical. Always follow the instructions on monitor timing in the dialogs when switching modes.

5. Processing

The Mode Switcher will:

  • Backup your current mode configuration
  • Restore the target mode configuration
  • Configure video outputs
  • Save changes to overlay

You'll see progress messages during this process.

6. Success Message

After successful switching, you'll see a completion message:

CRT Mode:

Successfully saved CRT Mode configs

REMEMBER:
- Keep monitor OFF during BIOS boot
- Turn on your monitor AFTER CRT Mode has been initialized and AFTER Batocera has fully booted

System will reboot now...

HD Mode:

Successfully saved HD Mode configs

System will reboot now...

7. Reboot or Power Down

The system will automatically reboot or power down depending if you are X11 or Wayland + X11. After reboot or new power cycle, you should see your display on the selected output.

OPTIONAL Blind Switch Watcher

On Steam Deck only, the CRT Script can offer an optional path back to HD Mode using a physical button chord (wired up through Triggerhappy / multimedia_keys.conf), so you do not have to open EmulationStation on the CRT when you cannot see the UI.

Why this exists

If the Deck boots in CRT Mode while you are away from a CRT, the built-in panel can stay black: CRT timings are not a usable signal for that LCD. The normal HD/CRT Mode Switcher is a dialog-driven tool and needs a working display, so without SSH or a CRT attached you could be stuck. This feature adds a blind, controller-only escape hatch: the watcher can see the chord soon after boot, and the script switches using HD settings you already saved the last time you used the switcher, with rumble so you know the reboot is coming even when you cannot see the screen.

When it applies

  • Hardware: Steam Deck (handheld screen counts as the HD display; same dual-output idea as elsewhere in this guide).
  • Service: The blind switch only works if crt_mode_switch_watcher is installed and enabled with the rest of the v43 CRT Script media-keys deploy (same installer pass that ships the watcher and crt-mode-switch-combo).
  • One-time setup through the switcher: This combo is only meaningful after you have already used the HD/CRT Mode Switcher at least once in both directions: CRT Mode → HD Mode, then HD Mode → CRT Mode again. That round trip creates and validates the HD-side backups the blind script expects. If you have never completed that cycle, stick to CRT TOOLS → HD/CRT Mode Switcher for switching to HD.

Important

Blind Switch Watcher will only be avaiable after a complete full HD/CRT round trip using the Mode Switcher has been made. This saved the HD settings that the blind switch restores. After enabling the device must be rebooted in order for the watcher to kick in. Save on both HD and CRT Mode.

How to do it (button combo)

Hold all four of these Deck controls at the same time for about 5 seconds (keep them held; do not tap; It does not matter which order you press, the moment they are all held down it will start the count):

Role in script Typical Deck hardware
SELECT View button (above the left analog stick)
START Menu button (above the right analog stick)
L1 Left shoulder
L2 Left trigger

In evtest, these map to BTN_SELECT, BTN_START, BTN_TL, BTN_TL2. If your unit names differ, use evtest on the Deck gamepad node to confirm all four codes exist before relying on this in the field.

How it feels

  • After the hold, the combo script takes a lock and waits; you should feel haptic rumble on the Deck right before the system shuts down for reboot into HD Mode. The rumble is a deliberate “you are about to shutdown” cue; if rumble is unavailable on your node, the script still proceeds after the hold.

Troubleshooting

Issue: Mode Switcher Not Found

Symptoms: Mode Switcher doesn't appear in CRT tools menu

Solutions:

  1. Verify CRT Script installation completed successfully
  2. Check if files are in correct location: /userdata/system/Batocera-CRT-Script/
  3. Verify Mode Switcher script exists: ls -la /userdata/system/Batocera-CRT-Script/
  4. Restart EmulationStation: systemctl restart emulationstation

Issue: Black Screen After Switch

Symptoms: Display goes black after mode switch and reboot

Solutions:

  1. Verify correct video output was selected
  2. Check batocera.conf for global.videooutput= setting
  3. Try switching back to previous mode
  4. Check /userdata/system/logs/BUILD_15KHz_Batocera.log for errors

Issue: Wrong Display Active

Symptoms: Mode switches but wrong display is active

Solutions:

  1. Verify video output selection matches your physical setup
  2. Check DRM sysfs: ls /sys/class/drm/card*-*/status
  3. Manually set output in ES: MAIN MENU → SYSTEM SETTINGS → VIDEO OUTPUT
  4. Re-run Mode Switcher with correct output

Issue: CRT Tools Missing in CRT Mode

Symptoms: CRT tools don't appear in EmulationStation after switching to CRT Mode

Solutions:

  1. Check if es_systems_crt.cfg exists: /userdata/system/configs/emulationstation/es_systems_crt.cfg
  2. Verify file contains emulatorlauncher entries
  3. Restart EmulationStation: systemctl restart emulationstation
  4. Check logs: /userdata/system/logs/BUILD_15KHz_Batocera.log

Issue: Configs Not Preserved

Symptoms: Emulator settings lost after mode switch

Solutions:

  1. Check backup directory: /userdata/Batocera-CRT-Script-Backup/mode_backups/
  2. Verify backups exist for both hd_mode/ and crt_mode/
  3. Check logs for backup/restore errors
  4. Try manual restore from backup if needed

Issue: User Custom Scripts Deleted

Symptoms: Your custom scripts are missing after mode switch

Solutions:

  1. This should NOT happen - user custom scripts are preserved
  2. Check if scripts are in backup: /userdata/Batocera-CRT-Script-Backup/mode_backups/[mode]/userdata_configs/scripts/
  3. Restore from backup if needed
  4. Report this as a bug if it occurs

Issue: Can't Select Video Output

Symptoms: Output selection dialog shows no outputs or errors

Solutions:

  1. Check DRM sysfs access: ls -la /sys/class/drm/
  2. Verify you're running as root
  3. Check system logs for DRM errors
  4. Try manual output selection in ES first, then run Mode Switcher

Issue: Only One Output Available

Symptoms: Only one video output detected, or trying to use same output for both modes

Caution

  • CRITICAL: A single output cannot be shared as both HD and CRT outputs at the same time
  • You must have at least 2 separate video outputs connected to use the Mode Switcher
  • Connect additional displays/outputs to your GPU/APU
  • Verify outputs are detected: ls /sys/class/drm/card*-*/status
  • If you only have one physical display, you still need 2 outputs configured (one for HD Mode, one for CRT Mode)
  • The Mode Switcher requires separate outputs for each mode - they cannot share the same output

Solutions:

  1. CRITICAL: A single output cannot be shared as both HD and CRT outputs at the same time
  2. You must have at least 2 separate video outputs connected to use the Mode Switcher
  3. Connect additional displays/outputs to your GPU/APU
  4. Verify outputs are detected: ls /sys/class/drm/card*-*/status
  5. If you only have one physical display, you still need 2 outputs configured (one for HD Mode, one for CRT Mode)
  6. The Mode Switcher requires separate outputs for each mode - they cannot share the same output

Reporting Issues

If you encounter bugs or issues during beta testing:

  1. Check the logs:

    tail -100 /userdata/system/logs/BUILD_15KHz_Batocera.log

  2. Report to Discord channel:

  3. Note your setup:

    • Batocera version
    • GPU/APU model
    • Display outputs available
    • Current mode before issue
    • Target mode attempted

Clone this wiki locally