FAQ and troubleshooting

Answers to common questions and solutions to common problems.

General

Is S.O.K free?

Yes. S.O.K is free and open source, under the MIT license. The source code is on GitHub.

Can S.O.K run on a NAS or a home server?

Yes: S.O.K Server is a Docker image with a web interface. It organizes your downloads with hard links, so torrents keep seeding, and can sort new downloads on its own.

Does S.O.K copy or move my files?

By default it moves them: after an organization, the files are no longer in the source folder. In Settings → Behavior, the file mode can copy them, or make hard links: the original stays where it is (a torrent keeps seeding) without taking more space. Check the preview before you confirm. If something went wrong, undo the rename from the message shown at the end or from the History page.

Is my library compatible with Plex, Jellyfin or Kodi?

Yes. The default names and folders (Series/Season 1/Series S01E01 Title.mkv, Movie (Year).mkv) follow the conventions these media servers expect.

Do I need an account or an API key?

No, not for TV shows and movies: TMDB and TVDB come with a built-in key. Only some services need a connection (Spotify, IGDB) or a personal key (OMDb, Last.fm). See Settings → API keys.

Does S.O.K need an internet connection?

Yes, to search the databases. Renaming and moving files happen on your computer.

Problems

“No files found”

  • Check that the folder contains files in a supported format.
  • Check that you are on the right page: a video folder added to the Music page finds nothing.

The search does not find my media

  • Type at least 2 characters.
  • Search for the original title, or the title in the language selected in Settings.
  • On the Movies page, add the year to the search text: Dune 2021.
  • Check your internet connection.

A file name is read wrong

The title, year or track number shown is not the right one: S.O.K does not know how your files are named. Add a pattern in Settings → Input formats and check it with Test.

The wrong series or movie was selected automatically

S.O.K selects the first result for the name it guessed from the file. Type another name in the search field and click the right result. The preview updates immediately.

Some episodes keep their original name

The file name has no season and episode number that S.O.K can read. Describe how your files are named in Settings → Input formats, for example {title} - Episode {episode}, or rename the file so it contains S01E02 or 1x02. Then add the folder again.

“Finished with errors”

Some files could not be moved. The most common causes:

  • A file is open in another program (a media player, for example). Close it and try again.
  • You do not have permission to write to the destination folder.
  • The destination drive is full or was disconnected during the move.

When a file with the same name already exists in the destination, S.O.K replaces it, unless Skip duplicates is on (it is by default). To keep the old file when it is replaced, turn on Backup before rename in Settings → Behavior.

“Files left in place” after an undo

These files were moved or deleted since the rename, or another file now has their old name. S.O.K never replaces a file. See History and undo.

“Please select a destination folder.”

The Destination area is empty, or the folder no longer exists. Choose it again.

A service shows “⚠️ Missing key”

This service needs a key or a connection. Configure it in Settings → API keys, or choose another service in Preferred API.

Windows says the installer is unsafe

Windows SmartScreen warns about software it does not know yet. Click More info, then Run anyway. Always download S.O.K from the Download page or from the GitHub releases.

macOS says S.O.K cannot be opened

S.O.K is not yet notarized by Apple, so macOS blocks it the first time. Click Done, then go to System Settings → Privacy & Security and click Open Anyway next to the S.O.K message. See Getting started.

Nothing happens when I open the AppImage on Linux

  • Check that the file may run as a program: Properties → Allow executing file as program, or chmod +x in a terminal. See Getting started.
  • Check that you downloaded the right version for your processor (uname -m prints x86_64 for Intel/AMD, aarch64 for ARM).
  • Start it from a terminal to see the error. If it mentions FUSE, start it with ./SOK_Linux_*.AppImage --appimage-extract-and-run.

Still stuck?

Open an issue on GitHub and describe what you did, what you expected and what happened. Add your S.O.K version (shown in Settings → About).