Client troubleshooting/FAQ

Client troubleshooting guide



Syncplay does not load on Windows

Problems running AppImage of Syncplay on Fedora

Problems with PYTHONPATH on macOS

  • See #276 for more details about this issue and how to resolve it.

Error: “Failed to recognize file format” when attempting to play any YouTube video via mpv on macOS

  • Using the mpv-based IINA instead of mpv seems to be a valid workaround. See #585 for a discussion on this issue.

macOS error: “This app was downloaded from the internet are you sure you want to open it?”

  • As Syncplay is just a small open source project we don’t have a paid Apple account allowing us to sign apps (or a build workflow designed to allow us to sign our software). As such, macOS users who want to use Syncplay have to either run it directly through Python or follow the instructions at to allow them to run the Syncplay disk image.

After specifying media folder, Syncplay spends so long looking for files that it times out

  • Don’t select any folder with hundreds of sub-folders because Syncplay looks through sub-folders of directories recursively.

Problems loading .m3u8 playlists

  • As per #408 Syncplay does not support the full .m3u or .m3u8 format. Please modify the file so that it has one filename per line and no comments.

I keep getting slowed down / rewinded, even though we’re all actually in sync

  • This can happen if one of the users has an unstable Internet connection.
  • If they have an unstable connection they may also be disconnected frequently disconnected for short periods, which is a result of Syncplay being quick to disconnect people if they go too long without sending a message to the server.
  • To get to the ‘Sync’ tab enable “Show more settings” in the Syncplay Configuration GUI and select the ‘Sync’ tab.
  • In the ‘Sync’ tab you can disable the slowdown and rewind features altogether. This can cause desyncs if someone has a slow computer, but avoids problems for people with unstable connections.
  • In the ‘Sync’ tab you can also try out the “Never slow down or rewind” others option if you are the one with the laggy connection, but it will cause problems if everyone in the room has that option enabled.
  • More information on the above features are contained within the guide on using the client, under the ‘Synchronisation Settings’ sub-section of ‘Configuration Window’.
  • This can also happen if someone changes their system time. Please don’t do that while Syncplay is open.

The Syncplay window is outside of the desktop area (e.g. because I disconnected a second monitor)

  • One option is to run the Syncplay client using the –clear-gui-data command line switch.
  • If you are on Windows 10, you can follow Microsoft’s advice on how to resolve the issue.

I updated Syncplay on Linux, but it didn’t update properly

  • If you’ve recently upgraded, make sure you used `make install-client` instead of `make client`

I tried installing on Windows 7 and it doesn’t show up properly

  • It is probably available if you go to the executable in the folder you installed it to even if the shortcut does not show up.
  • If you are using Windows 7 then we advise that you use portable version of Syncplay.
  • Windows 7 reached End of Life in January 2020 and may not be receiving necessary security updates from Microsoft.
  • We do not routinely remove support for older systems or media players, but we do not tend to devote resources to improving support for older software that has reached End of Life status.

I tried changing the chat font, but it didn’t work

  • Manually change the font by modifying the configuration file (syncplay.ini / .syncplay).
  • The relevant options for chat input in the [gui] group are: chatInputFontFamily, chatInputRelativeFontSize, chatInputFontWeight, chatInputFontUnderline, and chatInputFontColor.
  • The relevant options for chat output in the [gui] group are: chatOutputFontFamily, chatOutputRelativeFontSize, chatOutputFontWeight, and chatOutputFontUnderline.
  • For more details on this issue see #338.

Video playback issues

  • Check whether the problem still occurs without use of Syncplay, as it could be caused by your media player rather than Syncplay itself. You may need a lower resolution version of a file.
  • Try toggling the ‘Slow down on minor desync’ or ‘Rewind on major desync’ options under ‘Sync’ settings (check ‘Show more settings’ in Syncplay configuration window). If you are using mpv then it is recommended that you don’t enable ‘rewind on major desync’ without also enabling ‘slow down on minor desync’.

On MPC-HC, pauses are ignored

  • If you are have set the video filter to madVR then you will need to revert to the default filter or disable the ‘delay playback start until render queue is full’ option within madVR.

I use multiple servers. How do I remember different settings for each server?

For Windows users there are three main ways to do a profile system, and some work for other operating systems (some requiring appropriate tweaks):
(1) Multiple shortcuts. Create a shortcut to Syncplay per profile, and use the command line options to specify any value you want to change. See for a list of command line switches, but the main ones are –host, –name, and –password
(2) Multiple portable versions of Syncplay. A portable version of Syncplay is just a version of Syncplay which has a syncplay.ini configuration file within the same folder as Syncplay.exe. You can copy and paste the Syncplay folder and have a different configuration file for each version of Syncplay.
(3) Use per-folder configuration file. If you separate your media into folders for each of your servers and have a syncplay.ini in each, then any settings you specify in that file will be applied if you right click on that file and select to open it with Syncplay. This is explained at

“VLC has reported that the syncplay.lua interface script has not been installed” / Want to update to the newest version of syncplay.lua

  • This issue should be resolved in Syncplay >= 1.6.5.
  • If it persists and you are using a Snap version of Syncplay then try a non-Snap version of Syncplaty

On VLC, how can I run extra interfaces alongside the Syncplay interface (e.g. for HTTP)

  • For HTTP, if in Syncplay you enable ‘Show more settings’ on the Syncplay GUI then you can specify the following player argument to make it work –extraintf=luaintf:http. It is the same for other interfaces, as per the interfaces specified in the options (lua:http:telnet:skins2:qt:oldrc) – just make sure you include luaintf for Syncplay to be able to communicate with VLC!

Connection with server lost loop

  • This might be due to the use of Torrent software on your network. See #256 for details.

Problem with using network folders (including SFTP and samba)

  • Syncplay is not designed to work with network folders, but there might be workarounds to get it to work somewhat. See #639 for details.

Can’t load a bookmark in MPC-HC

  • Syncplay typically ignores seeks made when a file is first opened. As such, the MPC-HC’s ‘Remember File position’ and Favorites features will not usually work as expected if you are using Syncplay. However, when loading a bookmark for a file that is already open in MPC-HC 1.7.0+ the player seeks to the position rather than re-loading the file, so it can work if you load the file first.

Can’t connect to server

  • Connecting to port 8999 might be disallowed in some firewall configurations. Check your firewall settings if you are experiencing problems connecting to a server.
  • If the public servers are down then run your own server.

The media duration is not accurate

  • Media duration reporting is not always consistent between media players and set-ups. As such, in some cases Syncplay will warn about duration mismatches even when people are playing the same file. In many cases duration warnings can be ignored, but in some circumstances it helpfully indicates that a player is handling segment linking for multi-part files differently (and so may require configuration changes in the player or the use of offsets in Syncplay).
  • You can choose whether or not Syncplay warns about duration mismatches in the ‘Messages’ section of the Syncplay configuration window.

Trouble if someone’s file is shorter

  • If people are playing media of different lengths at the same time in the same room then the first person getting to the end of their file stops playback for all (except in some usages of the ‘offset’ facility detailed above). This cannot be fixed, although if you use controlled rooms then only the length of the room controllers’ files will matter.

Problems syncing DVD playback

  • Syncplay version 1.6.7 removed experimental support for syncing DVD playback. If you need to use this feature then please use Syncplay 1.6.6 with VLC 3.x.

Problems syncing video streams (e.g. YouTube videos)

  • Generally speaking Syncplay does better with mpv for video streams than VLC.
  • Try decreasing the video quality:
    • In VLC, you can do this via Tools ->Preferences-> Show all options -> Inputs/Codecs -> ‘Preferred video resolution’.
    • In mpv it is probably achieved via ‐‐ytdl-format=worst command line option or similar (see mpv manual).
  • Make sure you are using the latest version of your media player
  • If you’re using mpv then ensure you’re using the latest version of YTDL
  • If you are trying to play further into the video than has loaded then the media player may force you to an earlier position, causing sync problems – it may be best to wait a bit for the video to cache a bit before starting playback.
  • For mpv users on macOS, try using IINA instead. See #585 for a discussion on this issue.

Sync not quite accurate enough

  • Syncplay is not designed to have millisecond-level precision as this is not necessary for users to have a shared viewing experience.

Syncplay closes / crashes without a proper error message

  • On Windows open the syncplay.log file in %APPDATA% in a text editor to see see debug information.

Error “ImportError: No module named zope.interface”, but zope is installed

  • “the trick is go to into the installed zope module and add an empty file in the zope directory” (source)
  • For non-Windows users also ensure the directory that zope directory is covered within PYTHONPATH (see #72)
  • For non-Windows users zope should be installed with Twisted, so it might also be a sign that Twisted needs to be installed.

Error “This client does not support TLS”:

Manually setting the playback rate via the media player causes problems

  • Yes, manually setting the playback rate may cause problems. Syncplay generally assumes a playback rate of 1.0 and in some instances sets the playback rate to help get everyone more in sync.

Syncplay says it is up to date, but there is a newer version on the website

  • If this is in a week of release, it probably just means we’re waiting a week to ensure that no bugs are reported before pushing the update to the wider userbase.
  • If this is after a week of release, it probably means we forgot to update the version on the website and you should e-mail to remind us.

Syncplay says MPC-HC is an old version when it isn’t / problems with using SVP builds of media players

  • If a media player is running in administrator mode then Syncplay might also have to be running in administrator mode.

I want to use mpv with a custom input-ipc-path but Syncplay overrides it

  • See for a suggested patch to change this behaviour.

Why don’t you support for [X]?

  • Implementing and maintaining support for a media player can be a major commitment, as it can often require changes needed to the media player to support the relevant API features, and once that support is implemented it needs to be maintained through multiple versions of the media player software. As such, it is generally best for those taking the lead on such a project to be users of the media player itself. If you want support for a media player, please either become the ‘lead’ for that media player of find an active user of that media player to be the lead. Once a lead has been identified then we are happy to help them out,

What is the maximum size for playlists, usernames, etc.?

As discussed in #655, default limits are set out in and include:

  • Playlists: 10,000 characters / 250 items
  • Usernames: 16 characters
  • Filenames: 250 characters
  • Room names: 35 characters

These limits can be changed on private servers. For playlists and room names this requires a change to, and for others it requires running the server with the command line arguments –max-chat-message-length and –max-username-length with the new number specified.

How can I set-up Python on Windows so I can develop Syncplay

See for details.

Still have problems with Syncplay?