Skip to content
Documentation

FAQ & Troubleshooting

  • Make sure you have opened a folder that contains supported media files. Press O to open the folder picker.
  • Check that your files have recognized extensions. See the Media Capabilities page for the full list of supported formats.
  • If you are searching, click the clear button (×) in the search bar to reset the filter and show all files.

Videos don’t play (preview is blank or shows a placeholder)

Section titled “Videos don’t play (preview is blank or shows a placeholder)”

Video playback needs libmpv, which every released package bundles:

  • Linux (AppImage), macOS and Windows: mpv, ffmpeg and dav1d ship inside the package, so no media library has to be installed. The AppImage still uses the base system libraries your desktop already has (on Linux: ALSA libasound, the C++ runtime libstdc++, libdrm and the GPU drivers). If video still doesn’t work, the cause is usually the GPU: update your graphics drivers so they support Vulkan.
  • Building from source: install libmpv-dev (Debian/Ubuntu) or the equivalent for your distribution, plus libdav1d-dev for AVIF images. A from-source build links the system libmpv.

You can still view images and play audio without libmpv. Use the “Open in system player” button to play video files in your default media player.

The application won’t start or crashes on launch

Section titled “The application won’t start or crashes on launch”
  • Stale configuration: Try deleting your config.toml file. Its location depends on your OS; see the Configuration File page. The app will recreate it with defaults on next launch.
  • Vulkan / GPU issues: Media Sort uses wgpu for rendering, which requires Vulkan, Metal, or DirectX 12 support. Update your GPU drivers and ensure your graphics stack is functional.
  • Missing system libraries: The AppImage bundles its own X11/Wayland libraries, but it deliberately uses the host’s ALSA (libasound), C++ runtime (libstdc++), libdrm and GPU drivers — every desktop distribution ships those, so a missing one means the desktop itself is incomplete. A self-compiled build additionally needs libmpv-dev (and the equivalent of libx11/libwayland/libasound2 when they are not installed).

Delete the config.toml file at the location listed on the Configuration File page. Media Sort will create a fresh configuration file on next launch.

I upgraded from the old WPF v2.x version. Where are my settings?

Section titled “I upgraded from the old WPF v2.x version. Where are my settings?”

Media Sort automatically migrates settings from the legacy WPF application on first launch. If migration didn’t work, ensure the old config.json file exists at the expected location:

  • $CONFIG_DIR/Image Sort/config.json

If the file is present but settings still weren’t migrated, delete the new config.toml and restart the application. Migration runs only once, when no config.toml exists.

Can I use Media Sort entirely with the keyboard?

Section titled “Can I use Media Sort entirely with the keyboard?”

Yes. Media Sort is designed for keyboard-first operation. Every action (navigating folders, selecting files, moving, copying, deleting, renaming, creating folders, and managing pinned folders) has a keyboard shortcut. See the Keyboard Layout page for the complete reference.

Deleted files are moved to your operating system’s trash (Recycle Bin on Windows, Trash on macOS/Linux). They are not permanently deleted. While Media Sort is running, you can press Q to undo a deletion and restore the file to its original location. After closing the app, you can still manually restore files from the system trash.

Sorting actions (move, copy, rename, delete) modify file locations and names, but Media Sort never alters file contents. Metadata extraction is read-only. Image and video files are never re-encoded or modified.

If you encounter a bug or have a feature request, please open an issue on GitHub:

github.com/Lolle2000la/Media-Sort/issues