Tune and Recover an Xorg Video Mode with xvidtune

xvidtune lets you nudge a live Xorg video mode and pull yourself back from a blank screen if it goes wrong. Work through it slowly and you will also come away with a usable Modeline, without ever touching xorg.conf.

This guide covers xvidtune 1.0.4 from the installed x11-xserver-utils package. Allow about fifteen minutes, and keep a way to reach the machine without relying on the graphical display. You need an Xorg session connected through a local connection. The X server normally rejects mode changes from remote clients.

1. Check the installed command and display

Start with read-only checks in the X session you intend to adjust. These commands do not need sudo:

$ command -v xvidtune
/usr/bin/xvidtune
$ dpkg-query -W -f='${Package} ${Version}\n' x11-xserver-utils
x11-xserver-utils 7.7+9
$ printf 'display: %s\n' "$DISPLAY"
display: :0

Your package revision and display number may differ. What matters is that the binary resolves and that DISPLAY names the local X server. If DISPLAY is empty, start a terminal from the graphical session or set it using the session's normal mechanism. Do not guess another user's display.

2. Record the current mode before touching it

The -show option asks the X server for its current settings, prints an xorg.conf Modeline, and exits. Redirect it to a new file if you want a record:

$ xvidtune -show
Modeline "1024x768" 65.00 1024 1048 1184 1344 768 771 777 806 -hsync +vsync
$ xvidtune -show > xvidtune-modeline.txt
$ test -s xvidtune-modeline.txt && echo "saved current Modeline"
saved current Modeline

The values above are illustrative. Your output depends on the active hardware and mode, so do not paste them into a configuration file unless they are the values your own command printed. Keep the saved file somewhere you can find it, but treat it as a record, not a backup that gets applied automatically.

If xvidtune -show reports that it cannot open the display or the server does not permit the operation, stop here. Check that you are in the correct local X session. Do not work around an access-control error by copying another user's authentication files.

3. Open the interactive tuner

Run xvidtune with no options:

$ xvidtune

The window contains controls for moving the picture with Left, Right, Up and Down, and changing its size with Wider, Narrower, Shorter and Taller. Fetch reads the server's current settings into the controls. The program also disables video-mode hotkeys while it is running, so do not leave it open and assume those keys still work elsewhere.

Make one small adjustment at a time. Leave Auto off while exploring if you want to review each change first. With Auto enabled, the movement, sizing and restore controls are applied immediately. Do not treat the visible control values as proof that the server accepted them: use Test or Apply, then check the screen.

4. Test first, then apply deliberately

Use Test to switch temporarily to the selected settings. This is the safer point to check that text is centred, edges are visible and the refresh behaviour is acceptable. If the result is wrong, press Restore to return to the original values.

Recovery checkpoint: if the display becomes difficult to read, press the R key. xvidtune documents this as a way to restore the original mode when the screen becomes unreadable. If that does not work, use Ctrl+Alt+F3 to reach a text console when your system provides one, terminate xvidtune, and return to the graphical session using your usual display-manager method.

When the test looks correct, use Apply to adjust the current video mode to the selected settings. This changes the live X server, but it does not by itself edit /etc/X11/xorg.conf or another persistent configuration file. Press Quit only after the display is stable.

5. Capture a working Modeline

After applying a setting that you have tested, run the read-only export again:

$ xvidtune -show > xvidtune-working-modeline.txt
$ sed -n '1p' xvidtune-working-modeline.txt
Modeline "1024x768" 65.00 1024 1048 1184 1344 768 771 777 806 -hsync +vsync

Use the exact line from your machine as evidence when discussing a display problem or preparing a configuration change. Do not copy a random Modeline from the internet. The line describes timings for a particular mode and hardware combination; an apparently plausible value can still produce an unstable display.

If you later decide to make the setting persistent, treat editing Xorg configuration as a separate, service-disrupting change. Back up the relevant file before editing, keep a text-console recovery route, and make only one controlled change. To undo it, restore the backup or remove the new Modeline, then restart the graphical session using your normal system procedure. xvidtune itself does not provide that persistent rollback.

6. Use command-line mode switching sparingly

The non-interactive switches are useful for a quick local test:

$ xvidtune -next
$ xvidtune -prev
$ xvidtune -show

-next and -prev switch the X server to the next or previous video mode. They do not ask you to confirm the result first, so use them only when you know the mode list and have recovery access. -timeout SEC sets the test-mode timeout when you need a different duration.

If xvidtune was interrupted and video-mode hotkeys remain disabled, rerun xvidtune -unlock in the affected local X session. That option re-enables the mode-switching key combinations; it is not a tuning command.