Syncplay client guide
Using Syncplay 1.6.3
Opening a file with
Syncplay will run the client and load the file through your chosen media player (MPC-HC, MPC-BE, VLC or mpv). Alternatively, you can just open Syncplay and select the file later (e.g. through the shared playlist system).
Tips and tricks
- The Shared Playlist feature means anyone can add a file to a joint queue, and when you get to the end of one file it will automatically load the next one and rewind. To use this feature you will need to tell Syncplay the directories where it should try to find the files (e.g. by selecting File-> ‘Set Media Directories’ in the main Syncplay window). Please ensure the media directories you specify do not have way too many files in them or it will take too long to scan. You can add URLs to the playlist too (e.g. for a file hosted on a web server or a Youtube video) but you for this to sync you will need to ensure that everyone has a media player that supports the stream. The Shared Playlist will only switch to URLs that are on ‘trusted domains’ such as Youtube.com by default, but you can add trusted domains (e.g. right clicking in the Shared Playlist area and selecting ‘Set trusted domains.).
- You can input and see chat messages straight from the mpv player window – this feature is great for those who like text-based chat, but it is not currently supported by other media players. By default you have to press ‘enter’ to input a message, then press ‘enter’ again to send the message. Various configuration options are in the ‘Chat’ tab of the Syncplay configuration window (accessible after you tick the ‘Show more settings’ checkbox).
- You do not need to all be playing the exact same file. If the file has the same duration then it is probably fine. However, for the shared playlist feature to work you need to all have the same filename for a given file, so you may need to rename your files to ensure consistency between everyone in the viewing session.
- 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. However, Synclay does have a chat feature and this works best with mpv (see tip #2 above).
- Syncplay has experimental support for synchronising DVD playback for users of VLC. Let us know how well it works!
- 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!
- 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).
- Want to watch YouTube and other streams together? Use mpv for the best playback experience. Note: You will need to also install youtube-dl for most streams if you don’t already have it (and you have to keep it up to date).
- Having problems? Try the troubleshooting guide and if that doesn’t work then contact us.
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). 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).
- BASIC SETTINGS:
- Connection settings:
Server address – Address (hostname / IP) of server to connect to (optionally with port), e.g.
syncplay.pl:8999. 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 syncplay.pl 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. Syncplay supports MPC-HC, MPC-BE, VLC, mpv and mplayer2. For most purposes mpv has the best Syncplay compatability and is therefore the recommended player.
Path to video (optional) – Appears if “Show more settings” is checked. Location of media to be initially opened by the media player. This is necessary for mplayer2 but optional for other media players. For VLC and mpv this can be the URL of a stream, although your mileage may vary. In most cases it is best not to specify a file and instead just to use the shared playlist facility.
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. Arguments are stored on a per-player basis.
- Bottom of configuration window:
Help – Brings people to this guide.
Restore defaults – Resets Syncplay settings to their initial state.
Run Syncplay – Appears if “Show more settings” is checked. Runs Syncplay with chosen configuration options but does not save them to the Syncplay INI file.
Store configuration and run Syncplay – Saves the configuration to the relevant Syncplay INI file and runs Syncplay with this settings.
Show more settings – Allows access to some more configuration options, generally those that are more advanced or less frequently modified.
Enable shared playlists – Room operators can add files to a synced playlist to make it easy for everyone to watching the same thing. Configure media directories under ‘Misc’.
- Connection settings:
- 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)”. The readiness feature is explained in more detail in the ‘main window’ section of the guide.
- 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.
- Trusted domains:
Domains it is okay to automatically for Syncplay to ask the media player to switch to, e.g. as part of the shared playlist feature (one per line). If you connect to a domain name for a stream then the owner of that domain is able to see your IP address and provide you with potentially unsafe content, so only add domains that you know to be trustworthy.
- If you are lagging behind:
- CHAT SETTINGS (Access by enabling ‘Messages’ and going to the ‘Chat’ tab)
- Chat message input
Enable chat input via mpv – Enable chat input in mpv (press enter to chat, enter to send, escape to cancel). You need to be running mpv v0.28.0 and above for full compatibility with this feature. While inputting text you can use CTRL+V to paste text from the clipboard, but this will cause a slight pause. You can use the left and right cursor keys to change where your text cursor is.
Allow instant chat input (bypass having to press enter key to chat) – Skip having to press ‘enter’ to go into chat input mode in mpv. Press TAB in mpv to temporarily disable this feature. Usually to enter chat mode you have to press the enter key, type your message, then press enter again. In this default mode all other keys are as normal and will work with your usual mpv keybindings. However, you can change this default behaviour by enabling the ‘allow instant chat input’ option. When in this ‘instant chat’ mode you can press most of the keys on the alphabet rows (the ones starting Q, A, Z on English keyboard) and mpv will bring you straight into text input mode (e.g. press Q and it will start writing a message beginning with ‘Q’). This is useful, as it means that you not have to press enter and that you are less likely to accidentally triggering some mpv feature if you forget to press enter or type too fast. However, it still leaves the number row as normal mpv keys with their default keybindings so you can change volume, etc. In some cases when in the ‘instant chat’ mode you might actually want to trigger one of the keys from the alphabet rows, such as Shift+T to toggle always on top mode. To do this you first have to press ‘Tab’ to enter into the ‘Alphabet rows temporarily behave as normal’ mode. You press tab again to exit that mode.
Chat input font – Font used for when entering chat messages in mpv. Client-side only, so doesn’t affect what other see. The font scales down as the mpv window gets smaller, so you will want a larger size if you usually run mpv in a window rather than full screen.
Position of message input area in mpv – Location in mpv where chat text input prompt will appear when you press enter and type. If you are using ‘chatroom style’ output then the ‘top’ mode will make the input appear directly beneath the last chat message.
- Chat message output
Enable chat output in media player (mpv only for now) – Show chat messages within the media player itself (if supported by media player). This might also change how Syncplay notifications are displayed to use the chat system rather than the default media player OSD message system.
Chat output font – Font used for when displaying chat messages and notifications. This changes what you see on your screen, not what other people see on their screen.
Output mode – How chat messages are displayed. In the default ‘chatroom style’ mode the media player displays notifications followed by messages, with newer messages below the earlier ones in a manner similar to a standard chatroom or messenger service but with the chat messages disappearing after a number of seconds without any messages. In the ‘scrolling style’ messages scroll from the right side of the screen to the left and disappear when they leave the screen.
- Chat message input
- 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.
- Enable OSD Messages (Send On-Screen Display Messages to your Media Player to be displayed – requires OSD to be enabled on your media player).
- 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). Importantly, this is the list of directories that the shared playlist feature uses to locate files listed in the playlist.
- Core room settings:
- 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.
The following Syncplay features are available through the main window. For buttons that are icons only you can see what they do by hovering over them for the tooltip.
Playback options (accessible through the ‘Playback’ menu section and if you enable ‘Show playback buttons’ from the ‘Window’ menu section:
- Seek to time – Visible if ‘Show playback buttons’ is enabled through the Window. Seek (jump) to specified time. Putting an optional
-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.
List of who is playing what
If there are differences between what users are playing then the relevant items will show up in red.
- Room / User – Other rooms are only shown on ‘private’ servers where ‘room isolation mode’ is not enabled. A closed padlock icon indicates a ‘managed room’ (where only certain people can pause, unpause and seek) and an open padlock icon indicates an ‘unmanaged room’ (where anyone can pause, unpause and seek).
- Size – The filesize. This is usually rounded to an integer, but is rounded to one decimal place in the event that two files currently being played have a different file size but would round to the same integer. Size is not shown for streamed files.
- Length – The duration of the file as reported by the media player (in min:sec format). In some cases two identical files can have a different length because of the media players calculating the duration in a different way.
- Filename – The filename or URL of the currently playing file.
Shared playlist You can enable/disable this functionality for your copy of Syncplay by checking/unchecking the ‘Enable shared playlists’ checkbox. This will enable it for you, but not other. See Tip 1 at the start of this guide for an overview of this functionality The options in the context menu for the Syncplay are as follows:
- Open Media stream URL – This option is available if you select a URL (e.g. a Youtube stream). It will open the selected URL in your media player (so long as your player supports this). If you are using media streams then ideally you should be using mpv and YouTube-DL as this provides the best Syncplay compatibility. This is especially useful if you want to open a media stream from a ‘non-trusted’ domain without adding it as a trusted domain.
- Open Media – This option is available if you select a media file that is within your media directory. It will open the file in your media player, which will then change the playlist to that file if you can control the room.
- Add Trusted Domain – This option is available if you select a URL. Adds the domain from that URL (e.g. example.com) to the list of domains that Syncplay would automatically switch to if it appears as a URL in a playlist or if you double clicked the item in the list of who plays what. You can edit the list later to revoke your trust in a domain. If you connect to a domain name for a stream then the owner of that domain is able to see your IP address and provide you with potentially unsafe content, so only add domains that you know to be trustworthy.
- Remove From Playlist – Removes this entry from the playlist for you and others. If it is the currently playing file then people will automatically be moved onto the next file in the playlist.
- Shuffle Remaining Playlist – Randomly sorts all playlist entries subsequent to the one currently playing but does not change playlist selection or affect earlier entries in the playlist. All random combinations are treated equally so it might randomly shuffle it into the current order.
- Shuffle Entire Playlist – Randomly sorts all playlist entries and changes playlist selection to the first item in the playlist. All random combinations are treated equally so it might randomly shuffle it into the current order.
- Undo last change to playlist – Sets the playlist to what it was before the most recent change (even if you were not the one to make that change). This does not work if you were not in the room at the time of the change.
- Edit playlist – Brings up a dialogue which allows for easy text editing of the playlist items and copying/pasting to and from the playlist.
- Add file(s) to bottom of playlist – Brings up a dialogue where you can select one or more files to add to the end of the playlist. The result is the same as if you edited the playlist and manually entered the names. If you try to add files to the playlist that are not in a specified media directory then it will still add the files to the playlist but it will give you an error message and the entry will show up in red. In order for Syncplay to automatically open the file you need to add it as a media directory before or after adding the file to the playlist.
- Add URL(s) to bottom of playlist – The same as using the ‘edit playlist’ option and just adding files to the end of the playlist textbox, but you are not distracted by existing playlist entries (and if someone edits the playlist while you are writing it will not overwrite their change).
- Set media directories – Same as the option in the File menu and edits the same list as appears in the Syncplay configuration window under the ‘misc’ tab which is entitled “Directories to search for media (one path per line)”. The list of media directories tells Syncplay which directories to look in when trying to load a file from the shared playlist feature or if you try to open a file through the list of who is playing what. Please ensure the media directories you specify do not have way too many files in them or it will take too long to scan. 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!
- Set trusted domains – Sets the domains Syncplay will automatically switch to as part of the shared playlist system. If you connect to a domain name for a stream then the owner of that domain is able to see your IP address and provide you with potentially unsafe content, so only add domains that you know to be trustworthy. Youtube.com is a trusted domain by default.
Other shared playlist features:
- If you double click on a playlist item then it will attempt to open that item in your media player (which will then switch the playlist to that item if you can control the room).
- You can drag and drop items around inside the playlist.
- You can press the delete key on the keyboard to delete the currently selected item in the playlist.
- You can drag a file into the playlist, and position it where you want it.
- You can know a file on the playlist is one that is not on your PC (or at least not in your specified media directories) because the entry text will be in red.
- You can know that a media path on the list is one that is from a non-trusted domain because the entry text will be in purple.
- 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.
- I’m ready to watch! – Indicates to other users that you are ready to watch the media. This is used to help determine whether auto-play features will activate and other users will be informed of whether or not you are ready. By default when you pause from the media player it pauses and sets you as not ready and when you try to unpause it sets you to ready but does not unpause unless all others in the room are set as ready (and you can override this by pressing unpause whilst ready). You can change various related default behaviours in the ‘Play/Pause’ options tab of the Syncplay configuration window, including whether or not you are set to ‘ready to watch’ when you launch Syncplay and whether unpause always unpauses.
- Play when all ready / Min users – This is visible if in Window you enable ‘Show auto-play buttons’. When ‘Play when all ready’ is enabled it will automatically start playing 3 seconds after the minimum number of users are in the room and ready. If Syncplay detects differences between the different users it will treat them as ‘not ready’ for the purpose of this feature even if they have the “I’m ready to watch!” checkbox enabled.
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. If you are in a large group if people and this is happening too frequently then consider using ‘managed rooms’.
- “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.
- “You are now set as ready – unpause again to unpause” – See the above entry for configuring the ‘If you press play, set as ready and…’ synchronisation option for an explanation of this notification.
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:secformat – you can also use
.to denote milliseconds (e.g.
1.500would be one and a half seconds). By default the offset entered is the absolute offset, but you can prepend the time with
-to adjust the current offset or
/to calculate a relative offset between the current time and the specified time. It is generally better to avoid having to use this feature by playing the same file on all computers, or at least a file with the same duration.
- Set Trusted Domains – Sets the domains Syncplay will automatically switch to as part of the shared playlist system. If you connect to a domain name for a stream then the owner of that domain is able to see your IP address and provide you with potentially unsafe content, so only add domains that you know to be trustworthy. Youtube.com is a trusted domain by default.
- 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.
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
-n [name]– Specify username to use.
-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]
-r [room]– Specify default room to join upon connection.
-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/it]– Specifies the language to be used by Syncplay. Use en for English, ru for Russian, de for German and it for Italian.
--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
~/.syncplayon Linux) or Syncplay folder, for example:
room = TutorialVideos
- Playback thresholds – Set the value of the items
slowdownthreshold, rewindthreshold, fastforwardthresholdin the
[client_settings]group of the
.syncplayfile. Values are stored in decimal seconds, and changing the values can cause problems.