Syncplay client guide

This guide explains how you can use the Syncplay Client. You may also be interested in reading the Installation Guide, the Client Troubleshooting Guide and the Server Guide.

Using Syncplay 1.3.3

Opening a file with Syncplay will run the client and load the file through your chosen media player (MPC-HC, VLC, mplayer2 or mpv). Alternatively, you can just open Syncplay and select the file later.

Tips and tricks

  1. You do not need to all be playing the exact same file. If the file is more or less the same then that is fine, especially as you can use the offset feature if required.
  2. It is best to use Syncplay alongside a VoIP client, especially when watching something that is subtitled. We use Mumble, but other options are available such as Skype. You could also use a text-based chat solution such as IRC.
  3. Syncplay has experimental support for synchronising DVD playback for users of VLC. Let us know how well it works!
  4. Discuss with your fellow viewers whether or not to use the “Pause on disconnect” options (see Synchronisation Settings, below). It works best if everyone has it set up the same way!
  5. Syncing playback with a large group of strangers? Consider using managed rooms so only certain people can seek, pause and unpause, and one person lagging won’t mess things up for everyone (see advanced section, below).
  6. Want to watch YouTube and other streams together? Use mpv for the best playback experience. Note: You may need to also install youtube-dl.
  7. Having problems? Try the troubleshooting guide and if that doesn’t work then contact us.

Configuration window

The configuration window allows for various settings to be configured prior to Syncplay starting. Most inputs should display tooltips if you mouseover them (although this may not be the case for all setups), and these are often localised into your chosen language (e.g. German or Russian). Most settings have a tooltip that will appear when you mouse over it.

The Syncplay configuration window will always appear when you run Syncplay directly. If you open a file with Syncplay then the configuration window will only appear if the “Don’t always show this dialog” option is unchecked (or if you have failed to enter all required settings).

    • Connection settings:
      Server address – Address (hostname / IP) of server to connect to (optionally with port), e.g. Default port is 8999. By default Syncplay will list public servers in this combobox, and if you hold your mouse cursor over a server it should show a tooltip with more information about that server. The list is updated when Syncplay checks for software updates, and can be manually refreshed by pressing the “update list” button. Syncplay public servers are also listed on the right-hand side of the website.
      Server password (if any) – Password for the server. This is listed as ‘if any’ because public servers do not usually have password protection. Note: This is not encrypted.
      Username (optional) – Name that the server and other viewers know you by. If someone is currently using that name then an underscore will be added to the end. If you have not specified a name it will give you a random name such as “Anonymous3134”.
      Default room – Name of virtual room to join upon connection. You will only be synchronised with others in the same room on the same server. Room names are case sensitive.
    • Media player settings:
      Path to media player – Location of the executable for your chosen supported media player (mpc-hc.exe, mpc-hc64.exe, vlc.exe, mplayer2.exe, or mpv.exe on Windows; mpv, mplayer2, mplayer, vlc on Linux).
      Path to media file – Location of media to be initially opened by the media player. This is necessary for mpv and mplayer2 but optional for VLC and MPC-HC. For VLC and mpv this can be the URL of a stream, although your mileage may vary.
    • Player Arguments (if any) – Appears if “Show more settings” is checked. Use this to specify command line arguments for Syncplay to pass on to the corresponding media player. See VLC manual and mpv manual for command line switches for those players, and for MPC-HC go to Help->’Command Line Switches’ from the menu bar.
  • PLAY/PAUSE SETTINGS (Access by enabling ‘Show more settings’ and going to the ‘Play/Pause’ tab)
    • Set me as ‘ready to watch’ by default – Set yourself as ‘ready’ at start (otherwise you are set as ‘not ready’ until you change your readiness state)”
    • Pause when user leaves (e.g. if they are disconnected) – Pause playback if you get disconnected or someone leaves from your room. Results in message “<X> left, <Y> paused”. It is best if everyone in a room has this set the same way to ensure synchronisation between disconnected users and everyone else.
    • If you press play, set as ready and: … – When you press unpause (in Syncplay or your media player) then Syncplay will always set you as ‘ready’ and unpauses if you are already set as ‘ready’. With these options, you can configure in which circumstances Syncplay will also unpause if you are not already set as ‘ready’. Note: If you press pause this will  pause and set as ‘not ready’. In a managed room pausing/unpausing will just toggle whether you are set as ready or not.
  • SYNCHRONISATION SETTINGS (Access by enabling ‘Show more settings’ and going to the ‘Sync’ tab)
    • If you are lagging behind:
      Never slow down or rewind others (experimental) – Means others do not get slowed down or rewinded if your playback is lagging. Useful for room operators, but if everyone who controls this room uses this feature it can cause desync as the server is not designed to go for long times without getting a real position from users (causing approx 1 sec desync for every 2 minutes of playtime).
      Fast-forward if lagging behind (recommended) – Jump forward when out of sync with room operator (or your pretend position if ‘Never slow down or rewind others’ enabled, see above).
    • If others are lagging behind…:
      Slow down on desync – Reduce playback rate temporarily to bring you back in sync with other users (if your media player supports this feature). Note: This feature is not supported in MPC-HC. However, it works very well in mpv where it is far better than rewinding on desync.  On a managed room this only slow down if you are ahead of a room operator.
      Rewind on major desync – Seek/jump backwards to get you back in sync when you are too far ahead of any other viewers. On a managed room this only rewinds if you are ahead of a room operator.
  • MESSAGE/LANGUAGE SETTINGS (Access by enabling ‘Messages’ and going to the ‘Sync’ tab)
    • Enable OSD Messages (Send On-Screen Display Messages to your Media Player to be displayed – requires OSD to be enabled on your media player).
      Include events in your room  – Show OSD notifications for events relating to room user is in.
      Include events from non-operators in managed rooms – Show OSD notifications for events relating to non-operators who are in controlled rooms.
      Include events in other rooms – Show OSD notifications for events relating to room user is not in.
      Include slowing down / reverting notifications – Show notifications of slowing down / reverting on time difference.
      Include warnings (e.g. when files are different) – Show warnings if playing different file, alone in room.
    • Other display settings:
      Warn about media duration mismatches – Useful for when a segment in a multi-part file is missing, but can result in false positives.
      Language – Language to be used by Syncplay. Automatic/default language is determined based on system locale if possible.
  • MISCELLANEOUS  SETTINGS (Access by enabling ‘Messages’ and going to the ‘Misc’ tab)
    • Core room settings:
      Filename / File size information – Privacy mode for whether the name and size of the file you are playing is sent to the server, and if it is sent whether it is hashed to increase privacy. The more information that is sent, the easier it is for other people in the same room (or the same server if room isolation mode is disabled) to know what you are playing. This information is very helpful to flag instances where people are accidentally playing different files without knowing about it. On the other hand, for those who prefer their privacy they can send less information and take the functionality hit that goes with it
    • Syncplay internals:
      Don’t always show the Syncplay configuration window – Means the configuration window is not shown when opening a file with Syncplay (unless required configuration options need entering).
      Check for Syncplay updates automatically – Regularly check with the Syncplay website to see whether a new version of Syncplay is available. Note: There is usually a one week delay between when a release is made and when it is registered in the “automatic update” system so that bugs can be reported, but in this period newer versions will still be detected through the manual “check for updates” option in the Syncplay menu.
    • Directories to search for (one path per line) – Enter the directories where you store your videos into the “Directories to search for media” list. Syncplay looks through these lists recursively, so you don’t need to list sub-folders.  Because Syncplay will look through the sub-folders recursively, don’t select a directory with hundreds of sub-folders! When the main Syncplay GUI window is open, if someone else is playing something which is in one of these media folders (or the folder of the currently playing file) then an icon will appear next to the filename in the list of who is playing what. If you double click the filename it will switch to that file. If someone is playing a media stream (e.g. a YouTube video in mpv or VLC) then a different icon will appear in the list of who is playing what, and you can double click this to switch to that stream (assuming your media player supports that type of stream).
  • Appears at the bottom of the Configuration window if ‘Show more settings’ is checked:
    • Don’t store this configuration – Run Syncplay with the given configuration, but do not permanently store the changes.
    • Restore defaults  Reset all settings to the default configuration. This is all configuration options and window settings saved and paths saved, other than language.

Pressing the ‘Store configuration and run Syncplay’ / ‘Run Syncplay’ button will continue Syncplay start-up with the given settings (and save these settings unless ‘Do not store this configuration’ is checked).

Note: If you drag a media or executable file into the configuration window then it will set the relevant path input.

Main window

The following Syncplay features are available through the main window – button labels will not be visible if the window is not wide enough:

  • Join room – Leaves current room and joins specified room. You are only synchronised with others in the same room on the same server. If you are on a private server where room isolation is disabled then you can also join an existing room by double clicking on the room entry in the list of who is playing what. Room names are case sensitive.
  • Seek to time – Seek (jump) to specified time. Putting an optional + or - before the time denotes relative time forward and backward respectively. Time can be given in seconds or min:sec format.
  • Undo seek – Seeks to where you were before the most recent seek. Useful for if anyone seeks by mistake.
  • Play / Pause – Plays or pauses current media file.

Notable messages from the notification box are:

  • “Slowing down due to time difference with [user]” / “Rewinded due to time difference with [user]” – This means that your media player ended up too far in front of the specified user and has temporarily slowed down playback on your player or jumped to an earlier position to help keep you in sync. This is usually because someone’s computer isn’t powerful enough to play the file smoothly – it might be helpful for them to close unnecessary applications. Slowdown is not supported in MPC-HC 1.6.4.
  • “Reverting speed back to normal” – Slowing down due to time difference with user has ended (see above).
  • “File you are playing appears to be different from [user]’s” – This means that the filename, size and/or duration of the file that the user is playing appears to be different from the file that you are playing. This is for information only and is not an error. This message may appear when people are playing the same file, e.g. because the media players use different methods to calculate media duration, because people have given the same file a different filename, or because the file is still being downloaded and does not report the full filesize.
  • “[User] has left” – This means that the user is no longer connected to the server. If room isolation is enabled on the server then this could also mean that the user moved to a different room.

Noteworthy UI features:

  • Click to switch file – The list of who is playing what also allows for you to switch to the media file of another user by double clicking on the filename (or URL for a stream). Syncplay will only find files in the same folder as the currently open file, or in the files specified in the configuration GUI under Misc ->’Directories to search for ‘ (see above).
  • Double click to switch room – When on a private server (i.e. one where room isolation is not enabled) you can see the activity of other rooms in the list of who is playing what. In such cases, if you double click on the room name or any file in the room then Syncplay will switch you onto this room.
  • Drag in file –  If you drag a media file into the main window (or use the ‘Open media file’ menu option) then it will open that file in the existing instance of your chosen media player. If you hold down shift it might rewind the file to the beginning. but this feature should be considered experimental.

Advanced Syncplay features

‘Advanced’ section of menu bar

Several features are available under the ‘Advanced’ section of the menu bar at the top of the Syncplay window:

  • Set Offset – Allows for your media player position to be offset compared to other viewers (for when you are playing slightly different versions of a media file to other users). Time is expressed in seconds or min:sec format – you can also use . to denote milliseconds (e.g. 1.500 would be one and a half seconds). By default the offset entered is the absolute offset, but you can prepend the time with + or - to adjust the current offset or / to calculate a relative offset between the current time and the specified time.
  • Create managed room / Identify as room operator – In a managed room only those identified as ‘Room Operators’ people can pause, unpause and seek. If you create a controlled room then you will join the ‘managed’ version of that room (e.g. ‘+MyRoom:df908ee00155’) and will be given a password for that controlled room (e.g. ‘QY-907-577’). You and others can use this password to identify yourselves as Room Operators on that specific room in the future. Room Operators are identified in the userlist by an icon of a person holding a key. Room name/password combinations only exist for the server you created the room on, so if you change server you will need to generate a new room suffix.

Command-line switches

You can run Syncplay with the following command-line switches to alter Syncplay settings or behaviour:

  • --host [address] – Specify address of server to connect to (can be address:port).
  • --name [name] / -n [name] – Specify username to use.
  • --force-gui-prompt / -g – Force configuration window to appear when Syncplay starts.
  • --no-store – Disable the storing of configuration data (in .syncplay file). Path and window state information QSettings will still be stored if you use the GUI.
  • --no-gui – Run using using a command-line interface. [Note: This does not work for the default Syncplay Windows executable]
  • --room [room] / -r [room] – Specify default room to join upon connection.
  • --password [password] / -p [password] – Specify server password.
  • --clear-gui-data – Resets path and window state GUI data. Users must load Configuration GUI for this to work.
  • --player-path [path] – Specifies the player path – may need to be in quotation marks.
  • --language [en/ru/de] – Specifies the language to be used by Syncplay. Use en for English, ru for Russian and de for German.
  • --debug – Debug mode. Gives information on Syncplay communications with the server, VLC, mplayer2 and mpv (but not MPC-HC). On Windows this will be stored in %APPDATA%/.syncplay.log
  • [file] – File to play upon start.
  • -- – used as a last argument for Syncplay, used to prepend arguments that are meant to be passed to the media player (an alternative to the per-player arguments feature explained above).

Features that require manually creating/editing files

  • Directory-level configuration files – If you open Syncplay via “Open With” or otherwise specify a file when starting Syncplay (e.g. via the ‘Path to media file’ input) then Syncplay will check the current folder of that file, and all folders higher up the tree, to see whether there is a .syncplay or syncplay.ini file containing temporary setting (kind of like .htaccess files) that silently override one or more configuration options. The file should be in the same format as the .syncplay file contained within the %APPDATA% (~/.syncplay on Linux) or Syncplay folder, for example:
    • [client_settings]
      room = TutorialVideos
  • Playback thresholds– Set the value of the items slowdownthreshold, rewindthreshold, fastforwardthreshold in the [client_settings] group of the .syncplay file. Values are stored in decimal seconds, and changing the values can cause problems.

VLC ‘syncplay.lua’ not found? Any other problems?