SSLScrobbler v0.34

SSLScrobbler is a Scrobbler for Serato DJ and Serato ScratchLive (http://www.serato.com/) written in PHP. See https://www.last.fm/about/trackmymusic for an explanation of Scrobbling.

SSLScrobbler is designed to update Last.fm, Twitter and/or Discord when a track is playing or played.

It is so named because Serato DJ used to be called Serato Scratch Live (SSL) when I started this project.

SSLScrobbler can easily be customed to, for example, show what's currently playing on a projector, or send information to OBS (Open Broadcast Studio), or used to control other actions based on track listing.

Serato DJ itself logs plays to a binary history file during playback. This app reads the binary file and models what's going on.

The app works on OS X (Mac) and Windows.

-1. A NOTE ON REPORTING BUGS

It may not do everything you want, and I certainly haven't tried every function of Serato to see what happens.

If you encounter bugs 🐛 🐜 🐞, please copy-paste the entire output from the program into a new ticket for me on my GitHub, along with a description of what you expected to happen as well as what actually happened 👍

https://github.com/ben-xo/sslscrobbler/issues

0. CONTENTS

OPERATING SSLSCROBBLER

Installation
Getting Started
Quick HOWTO
Options

HOW IT WORKS
ADVANCED USE
TROUBLESHOOTING
FOR DEVELOPERS

Plugins
Unit Tests
Architecture

THANKS & SHOUTS
FAQ
CREDITS & LICENSE

1. OPERATING SSLSCROBBLER

You should start SSLScrobbler before starting Serato DJ!, and then close it down after closing down Serato DJ. If you have no idea how to start it, See 1.2 for the 'Getting Started' guide.

To close SSL Scrobbler, press Ctrl-C.

SSLScrobbler will read the current 'session' file from the Serato DJ history folder. It will follow from session to session, but use the -i option if you already have a session open.

1.1 Installation

1.1.1 macOS

There is an app you can download from https://github.com/ben-xo/sslscrobbler/releases

SSLScrobbler needs no particular installation, although if it's not already, you might like to install terminal-notifier ("brew install terminal-notifier" - If you don't have the brew command, install Mac Homebrew from https://brew.sh/ )

SSLScrobbler can also be started from Terminal, and has more options this way.

To start from Terminal you will need PHP installed (recommended version 8.4). You can install PHP through Mac Homebrew https://brew.sh/. Once installed,

    brew install php@8.4
    # (or just brew install php)

See "Getting Started" for more.

1.1.2 Windows

I haven't tested this part in a long time. I have never owned a Windows 10 or Windows 11 machine as a primary machine. I welcome any feedback.

Try installing PHP by following the instructions on https://www.php.net/

You should install PHP 8 and Growl. You must reboot after installing these, even if it doesn't ask!

If you're on Windows XP, 32-bit Vista or 32-bit Windows 7, you can download and install PHP from https://windows.php.net/download/ (You probably want the 'Installer' nearest the top of the page, unless you know better.)

I strongly suggest you make the following change to your php.ini file (which can usually be found in C:\Program Files\PHP). Open the file in Notepad, and then find the line which says...

    display_errors =

...and change it to On if it is Off.

SSLScrobbler is best started from a DOS box / Command prompt (see below)

1.2 Getting Started

SSLScrobbler is designed to be run from the command prompt / terminal, but on macOS there is also a GUI to help you get started.

1.2.1 TO START

I use this app through Terminal on macOS. But, there is a macOS GUI version too. On Windows you must use Command Prompt. There is a guided-prompt setup mode. Read on.

1.2.1.1 macOS (super-easy method):

The simplest way to get started is to use the macOS app.

Download the macOS.zip file from https://github.com/ben-xo/sslscrobbler/releases
unzip it to get SSL Scrobbler.app (with a nice vinyl record icon)
Option-click it and choose "Open", then confirm you are sure that it's okay
The app will ask you for permission to use SystemUIServer. Say yes. This is so we can pop up questions.
It will then pop up some questions. Just follow the prompts.
Then start Serato DJ and watch what happens!

1.2.1.2 macOS (traditional method / more options):

It is more flexible when used from Terminal.

Open Terminal (you can open it quickly from Spotlight)
Drag the file historyreader.php into the Terminal window, and hit enter. It should say something like:
```
 $ /Users/ben/Downloads/sslscrobbler/historyreader.php 
```
For help and information on options, type --help before hitting enter. e.g:
```
 $ ./historyreader.php --help
```
For the guided setup mode, try --prompt .

1.2.1.3 Windows:

There's no GUI version for Windows yet. Sorry.

Open a Command Prompt. You can do this by clicking 'Start' -> Run -> typing "cmd" and pressing enter.
Type php and then drag the file historyreader.php into the command prompt, and hit enter. It should say something like:
```
 C:\> php "C:\Documents and Settings\ben\Desktop\historyreader.php"
```

For help and information on options, type --help before hitting enter. e.g.:

 C:\> php "C:\Documents and Settings\ben\Desktop\historyreader.php" --help

For guided setup mopde, try --prompt .

1.2.2 TO QUIT

To quit SSL Scrobbler, click on its window and press Ctrl+C. (or in the macOS app, press the quit button in the bottom right)

1.3 Quick HOWTO

TO SCROBBLE AS YOU PLAY:

php historyreader.php -L lastfmusername

TO SCROBBLE THE PREVIOUS SET (e.g. from your gig last night):

php historyreader.php -L lastfmusername --post-process

TO SCROBBLE SEVERAL PEOPLE IN THE ROOM:

php historyreader.php -L lastfmusername -L lastfmusername2 -L lastfmusername3

TO TWEET AS YOU PLAY

php historyreader.php -T twitterusername

TO MESSAGE DISCORD AS YOU PLAY

php historyreader.php --discord webhook-name

MAKE TRACK DATA AVAILABLE FOR OBS (OR WHATEVER)

php historyreader.php -J 8080

MAKE TRACK DATA FOR BUTT (OR WHATEVER)

php historyreader.php -ln nowplaying.txt

1.4 Options

Add the following options to the command when running from Terminal / DOS to control the behaviour.

If you supply no options, SSLScrobbler will show you that it's working, but the information won't be sent anywhere or available to use except by reading the output; so you will want to study the options (especially the options from --plugin-help)

1.4.1 Basic options

-h or --help A reminder of this information.

--prompt Guided setup mode.

You will be asked a series of yes or no questions. (Not all options are available in this mode).

-l or --log-file <file>: Write the output to a file. (If this option is omitted, output goes to the screen)

-i or --immediate Do not wait for the next history file to be created, but use the most recent one.

You must use this option if you started SSLScrobbler mid-way through a session, or if you had to restart SSLScrobbler for some reason.

This option is ignored if you specify the full path to a specific history file.

-v or --verbosity <0-9>: Increase the amount of information shown in the console. If you really want to see a lot about what's going on, try -v 9 .

You should try -v 9 and save the output if you are having problems, before reporting a bug to me, or contacting me for advice...

-p or --post-process Immediately processes everything in the last history file. Ideal for scrobbling that set you played last night.

Now Playing text file options All of these options output the current playing track to a file, but in different formats.

-ln or --log-track <file>: log the current playing track to a file (e.g. for streaming)

The file will contain the text Artist Name - Song Title when a song is playing, and the file will be empty the rest of the time.

-ls or --log-serialized <file>: log the current playing track to a file in PHP serialized form. This contains more info, but is not human readable - it's useful if you want to build other PHP scripts for a web server.

-lt or --log-tostring <file>: log the current playing track to a file in a fuller representation, like what comes out in the console log, e.g.:

PLAYED:1 - ADDED:1 - DECK:1 - Artist - Title - 0:0

Most people want -ln

Last.fm options: -L or --lastfm <username>: Scrobble / send 'Now Playing' to Last.fm for user <username>.

The first time you specify this, it will ask you to authorize the app to your Last.fm account. The authorization information is stored in a file called lastfm-<username>.txt

NOTE: you can include -L multiple times and scrobble to multiple accounts.

Twitter options: -T or --twitter <session>: Post tracklists to Twitter. It will tweet once for every 'Now Playing'.

The first time you specify this option, it will ask you to authorize the app to your Twitter account. The authorization information is stored in a file called twitter-<session>.txt

NOTE: you can include -T multiple times and tweet to multiple accounts.

Discord options: `--discord <sessi

Sslscrobbler

Install / Use

README