What is Syncplay?

Syncplay is a tool that allows you to synchronize media players between multiple clients, which allows you to watch video files, that you and your friends have, together on different machines, without shouting 3.. 2.. 1.. every time someone takes a break for a second. It works by either one of the users providing a server on their local machine for the clients to join, or everyone joining a public server.

While setting up a server for your own is not that difficult, it's quite laborious to do it every time you want to watch something. Public servers are also rather rare and sometimes not reachable all the time. Plus some people would prefer to have their own server running anyways. So here's how!

This guide has been tested a Linux machine running Ubuntu 14.04LTS and a Raspberry Pi running Raspbian Jessie.

syncplay.jpg Syncplay client on a windows machine

Building and installing Syncplay

For our server, we are going to install syncplay in /opt/syncplay and create a new system user to run it. Depending on your permission settings, you will have to run the mkdir and chown command via sudo, since your user will (and should!) most likely not have write-access to /opt


sudo useradd -r syncplay
sudo mkdir /opt/syncplay
sudo chown syncplay /opt/syncplay
cd /opt/syncplay

To make things easy, you can use sudo chown syncplay:mygroup /opt/syncplay instead, and modify the permissions of the folder temporarily via sudo chmod -R 775 /opt/syncplay, so you can perform the following steps with your currently logged in user. If you don't want to adjust the permissions, you can also use sudo su syncplay to switch your user to syncplay, since this is the user that owns our program folder and has the right to do all the following changes.

We now need to get the latest release from the Syncplay repository, in order to install Syncplay on our machine. If you have git installed, you can simply use it to do this, otherwise we will have to just download and unpack the archive. Both methods are shown below, you only have to do either of them.


# If you have git installed (Replace 9752aad with the id of the latest release tagged commit!)
git clone https://github.com/Syncplay/syncplay.git ./
git reset --hard 9752aad

# If you just want to download the archive without git
# Please note, that this url and the name of the folder will be different for later releases
curl -sL https://github.com/Syncplay/syncplay/archive/1.3.4-RC2.tar.gz | tar xz
mv syncplay-1.3.4-RC2/* ./
rm -R syncplay-1.3.4-RC2/

As a last step, we now have to build syncplay and let it install all its dependencies. Usually, this should work without any problems, if you do however encounter any, you might want to check the Syncplay install page for more information on the software dependencies and their packages.


sudo chown -R syncplay *
sudo make install

Once the installation is completed successfully, we are able to run the server via syncplay-server. Starting it for the first time will also give us a value for the --salt parameter, that we will have to use later on, so better note this somewhere.

install.jpg Successful Syncplay installation

Troubleshooting our installation

If your installation worked without any problems and running syncplay-server afterwards did not yield any errors, aside the note that you may add the --salt parameter to the next startup, you can skip this paragraph completely.

error.jpg A dependency error yielded by Syncplay

The most common error experienced when attempting to run Syncplay for the first time is, that it complains about missing python dependencies. This has been the case especially when attempting to run it on a Raspberry Pi. The following code snippet offers a simple way to solve this problem. Please note, that you can use either of those attempts, though when running it on a Raspberry Pi, you want to use the latter, since Raspbian does not have all the build tools installed to properly build the required python libraries.


# Fix missing dependencies by installing the python dependencies via pip (Generic)
sudo apt-get install python python-pip
pip install twisted
pip install PySide

# Fix missing dependencies by installing the pre-packed packages (Raspberry Pi)
sudo apt-get install python python-twisted python-pyside

If after this, your installation still yields dependency errors, make sure to check the Syncplay install page again to make sure, you have all the required dependencies installed.

Getting our start command

The Syncplay server offers a variety of flags we can use to customize its behaviour, which are documented on their website, for this example, we are going to set a server MOTD, a password, a custom port and our salt.

Syncplay loads its MOTD from a file, so we are going to create a file and add our message. This step is completely optional, but worth mentioning, since MOTDs are a nice way to personalize your server a bit. After that, we can simply apply all parameter according to the documentation on the Syncplay website.


# If you want to use an motd, create a file with some content
echo "Welcome to our Syncplay server!" > /opt/syncplay/motd.txt

# Now start the server with all our parameters. - Everything besides --salt is technically optional!
# You can run a syncplay server without password, on the default port (8999) and with no motd.
syncplay-server --password myPassword --port 4567 --salt XXXXXXXX --motd-file /opt/syncplay/motd.txt

We can run this in the background using a tool like nohup or screen, but ideally, we would want an easier way to handle our syncplay server. If you only want to do it sporadically, you can copy the command from above into a shell script and just start the server whenever you need it. In this case, you're done with your set up at this point.

However, if you want to do it all perfect, which in this case means easy-to-handle and restart-save... we are going to do that now!

Building a Syncplay service

First, we are going to create an init script that our Syncplay service will run on. If you have not installed screen, you will also have to do that now, since the init script uses screens to background the service.


# If you have screen not installed
sudo apt-get install screen

sudo nano -w /etc/init.d/syncplay

We are going to put the following init script into the syncplay service file. The script will start a screen called syncplay-server upon starting, with the arguments given in the script and terminate it when the service is stopped. The script will also display you if a syncplay server is running if you ask for its status


#!/bin/bash
# Start script for Syncplay server

server_start()
{
    running=`screen -ls | grep syncplay-server`
    if [ "$running" == "" ]; then
        screen -dmS syncplay-server
        screen -S syncplay-server -X screen syncplay-server --password myPassword --port 4567 --salt XXXXXXXX --motd-file /opt/syncplay/motd.txt
        echo "Syncplay sever started"
    else
        echo "Syncplay server already running"
    fi
}

server_stop()
{
    running=`screen -ls | grep syncplay`
    if [ "$running" != "" ]; then
        screen -ls | grep syncplay-server | cut -d. -f1 | awk '{print $1}' | xargs kill
        echo "Syncplay sever stopped"
    else
        echo "Syncplay server not running"
    fi
}


case "$1" in
    start)
        server_start
        ;;

    stop)
        server_stop
        ;;

    restart|reload)
        server_stop
        server_start
        ;;

    status)
        echo "Syncplay servers found (if any):"
        screen -ls | grep syncplay-server
        ;;

    *)
        echo "usage: $0 start|stop|restart|reload|status" >&2
        exit 1
esac

exit 0

On to the final step, we only have to make our init script executable now and our server is ready to go!


sudo chmod +x /etc/init.d/syncplay

Please note that screens are user-dependent. Screen manages a separate pool of screens for every user, so if you start the service as user syncplay, you might not be able to stop it when logged in as another user. This doesn't really matter though, since syncplay is a system user dedicated to the purpose of running this service, so we should always be using it for handling the service.

usage.jpg Example usage of the Syncplay service