Scrobbling with Giocoso

1.0 Introduction

"Scrobbling" is the slightly odd name that means 'sending details of the music to which I've been listening up to a cloud service' -and the 'cloud service' everyone usually thinks of in this context is The vast majority of software music players for the PC do this reporting because it can be a useful way of building up a long-term history of your listening habits. That in turn can lead you to realise you've over-listened to this composer's music and under-listened to this one, and thus the history of your past listening can guide and influence your future adventures in music.

Giocoso can scrobble details of everything it plays to, just as all those other software music players do. However, it doesn't do so by default (for obvious privacy-related reasons) and if you want it to scrobble, you must first configure it to do so. Those are two entirely separate steps. You can configure-to-scrobble without then enabling actual scrobbling, in which case no scrobbling takes place even though it could do so. You can also not-configure-to-scrobble but still ask Giocoso to perform scrobbling, in which case no scrobbling takes place because Giocoso simply doesn't know how to. You have to do both things to get scrobbling working in other words, and this article will tell you how.

2.0 Configure to Scrobble

Configuring to scrobble is a once-off affair that involves granting Giocoso the right and privilege to access your account. Once granted, Giocoso will retain the ability to scrobble indefinitely, unless you explicitly revoke its privileges from within your account.

Obviously, to start with, you must already have a account! It is free to create one. The entire process of signing up for a account is, however, nothing to do with me or Giocoso, so I won't document that process any further, other than to say after you've signed up (which costs sharing your email address), you'll receive an account activation email from them: click on the button to activate your account and you're good to go.

2.1 Creating an API Key

Assuming you have created and activated a account and have managed to log into it for the first time, you then need to create an API account, which sounds complicated but really only means "set up some security credentials so that third party software can access my account for the purpose of recording new 'listens' into it". You create an API account by visiting the relevant page at I'll step you through that process now, pointing out before I do so that any email addresses you see in screenshots are temporary/fake ones!

You first get taken to this page:

You need to fill in the screen pretty much as you see here: the contact email needs to be the same one you used to open your account. The application name can actually be anything you like, but 'Giocoso' is a nice, simple suggestion that makes it clear which application you are authorising to access your account, so I'd recommend sticking with that. The application description can also be any free text you fancy, but I'd again recommend sticking with what you see above, as it makes it unambiguously clear why this API account is being created. The callback URL and application homepage entries should both be left blank, as you see me doing.

Click the red Submit button when you're ready, and the screen will change to this:

This page now shows you the two crucial bits of security information needed to allow a third party to post to your account (and again, please note that the account I'm using for these screenshots is fake and thus the credentials shown in them won't work in real life!). The API key and Shared secret are long strings of seemingly-random digits and characters that together provide the functional equivalent of a username and password that a program like Giocoso can use. You will therefore need to be able to quote these two bits of information accurately in just a moment: it's therefore a good idea to keep this webpage open, or to copy-and-paste those two security credentials into a text editor, keeping them safe until they've been given to Giocoso.

2.2 Giving Giocoso the Security Credentials

You now need to launch Giocoso in a special scrobble-configuration mode, by issuing the following command in a new terminal session:

giocoso --scrobble-config

As soon as that command is submitted, you'll see the screen do this in response:

You will note that Giocoso first creates a new text file called $HOME/.config/giocoso-scrobbler: this file will eventually contain an encrypted version of your API Account credentials. Losing that file will mean Giocoso loses the ability to scrobble. However, you can create a new API account and go through this scrobble-config process again, as many times as you like, so losing the file isn't actually the deal-breaker it might sound like.

When you're ready, press any key to continue (or Ctrl+C to quit, of course). The terminal now displays a new message:

As you can see, you are being prompted to type in your API key. That's the first piece of seemingly-random text that was visible on the 'API account created' screen shown earlier. You simply copy-and-paste in the relevant credential:

When you press [Enter] to submit that API Key, you're then prompted for the Shared Secret:

You now again copy-and-paste the Shared Secret from the API Account Creation screen into the terminal session:

When you have pasted that credential in, you press [Enter] to submit it... and quite a lot of things will then happen, hopefully automatically! If all goes as it should, you'll see this happen in your terminal session:

Giocoso has taken your two credentials and turned them into an enormous, blue URL which points to a web page where you will be able to sign in to your account and 'authorise' Giocoso to use those credentials. Having done that, Giocoso should then be able to open your system's default browser at that long, blue URL address ...but sometimes this fails to happen as automatically as it should! If you don't see a browser window open automatically, just select and copy the blue URL yourself, open a browser manually, and paste in the URL yourself.

In my case, happily, everything did happen as it's supposed to:

You can see that a Firefox browser window has opened, already visiting the webpage identified by the blue URL. All I have to do is log in to using my username/password combination I used when creating my account originally:

As you can see, as soon as you freshly log in to, you are taken to a 'Connect application' screen. All you need do at this point is click the red 'Yes, Allow Access' button:

The page should show a green 'you have granted permission...' message, and your job at is now over. You can simply close the browser window now and switch back to the Giocoso terminal session, which has been waiting patiently in the background all this time.

Giocoso will be stalled at a 'press any key to continue once you've authorised me' type of message. Since you have just authorised it, do what the message tells you to do and press a key:

Giocoso responds by telling you that the access credentials have been saved in that giocoso-scrobbler file/folder we saw got created earlier. Giocoso's ability to scrobble music plays to has now been established and, provided you never lose that credentials file, will never need to be re-established again.

3.0 Getting Giocoso to Scrobble

As I mentioned earlier, having the ability to scrobble isn't the same thing as practically scrobbling. To make scrobbling actually happen, you have to tell Giocoso to do so, every time you launch it. To do that, you use the --scrobble runtime parameter as you run the program. You can also configure SCROBBLE=Yes in the Giocoso persistent configuration file, which then means you don't need to remember to supply the runtime parameter every time you launch the program.

To use the runtime parameter, you just add it to the command to launch Giocoso as you would any other runtime parameter. For example:

giocoso --dbname=main --scrobble

That will trigger a random music play using the 'main' database as the source of information about what music exists -and when the music play has finished, the fact of that play will be transmitted to

So, let's start by considering the current state of play of my account (by visiting its Profile page):

As you can see, it's blank: there's an instruction to 'start scrobbling' shown, but no actual scrobbles recorded. Knowing that we are thus starting from a blank slate, let me launch Giocoso with the command I mentioned before, including the --scrobble runtime parameter:

As you may be able to see in the background, nothing about the Giocoso program window indicates whether it will or won't scrobble: the presence of the runtime parameter makes no difference to the main program display. The parameter does make a difference, however, when the play of music comes to an end:

Now you see a 'Scrobbling... - OK!' message at the bottom of the main recording-details part of the screen. This message indicates that the transmission of the just-completed play details to has been successful. You'll see this message every  time a recording finishes being played, even if Giocoso has been asked to play more than one 'selection' in a session, though it will disappear quite quickly as the next recording play in the cycle begins.

At the end of a complete cycle of selections (or, as in the case of my last screenshot, when only a single recording was requested, because Selections is 1), you see the three white text messages you see at the very bottom of that last screenshot, one of which reads 'Scrobbling Complete!'. Again, that's an indication that all scrobbling activities have been completed successfully.

And if we check our account now, we see this:

At this point, you should see that knows the name of the composition Giocoso just played, along with its composer. Your scrobbling journey has begun!

That example was performed by adding the --scrobble runtime parameter to the command used to launch Giocoso. An alternative is to edit the Giocoso persistent configuration parameter file (using the command giocoso --editconf) and finding the parameter SCROBBLE. It will probably be set to 'No', because that's the default, but if you set it to 'Yes', you will no longer need to remember to supply the runtime parameter. The configuration file will switch on scrobbling anyway. Within the configuration file, parameter values can be 'Yes', 'YES', 'yes' or even 'YeS'... the case doesn't matter and Giocoso just sorts it all out anyway.

Finally, something you actually already know from the earlier description of switching on scrobbline: if the persistent configuration file says SCROBBLE=NO, but you launch Giocoso with --scrobble, the runtime parameter overrides that configuration file setting. The reverse is not the case, however, because there is no runtime parameter that means 'do not scrobble'. So if the persistent configuration file says SCROBBLE=YES, there is no runtime parameter that can contradict or override that.

4.0 Recording-based Scrobbling

Once you've configured to let Giocoso scrobble; and once you've told Giocoso to perform scrobbling, you need to know that the way Giocoso scrobbles is quite different to the way other software music players tend to do it!

Those other music players tend to be 'track-centric'. That is,if you play a 3-movement piano concerto, they will usually scrobble the details of each movement as it completes. You end up with three separate scrobbles, separated by however many minutes it takes for each movement to play. If you were to interrupt the playing of the recording in the middle of the third movement, would still know that you had played the first two movements.

Giocoso doesn't do things this way, however: it is composition (or recording)-centric. If you play the entire recording, then it agrees you've listened to Piano Concerto No. 5 and will scrobble its three movements to in one sitting. You still get three movements scrobbled, as those other players would do; but they now all have the same timestamp, because they were all submitted at the same time. This approach means that if you were to interrupt playback of the concerto in the third movement (by pressing Ctrl+C), Giocoso won't scrobble anything at all. It will be as if you'd not listened to any of the recording. The fact you listened to ⅔rds of it will not be registered anywhere.

Essentially, Giocoso takes the view that if you walk out of a performance in the concert hall half-way through, you can't really claim that you heard 'the symphony' or 'the concerto': you only heard 'bits of it', and partial listening experiences don't count. Classical music doesn't work that way, and neither does Giocoso!

So, be aware that interrupting Giocoso playback part-way through a recording means nothing of that recording will be scrobbled. On the other hand, it's possible to run Giocoso with the --selections=x parameter, meaning that Giocoso will play x separate recordings, one after the other. In such a scenario, Giocoso will scrobble each recording as it completes its playback. Let's say you ask for --selections=9, for example: if you interrupt Giocoso as it's playing back the fifth recording in the cycle of plays, then four previous recordings will have been played to completion and thus scrobbled before that point. The details of that fifth recording will not be scrobbled, of course, because you interrupted playback before it completed; but the fact you listened to four other recordings before that point will be registered at

5.0 Scrobbling with Embedded Cuesheets

Most programs rip CDs to digital files on a per-track basis. Start with a CD containing a four-movement symphony and you are likely to end up with 4 separate FLAC files sitting in a folder on your hard disk. Giocoso is happy to work with this arrangement: it sees a folder full of FLAC files as a single 'recording' and plays all the files found inside a folder as a single work, without interruption, until the last one completes. That would result in Giocoso performing a single scrobble to as the last track completes of all four tracks in one sitting.

Some ripping programs, however, prefer to rip all four movements of that recording to a single FLAC track (usually referred to on this website as a 'superFLAC'). A superFLAC contains all the individual tracks from the original CD 'within' itself, logically; but there's only one physical FLAC involved. Confronted with a single digital file, how does a music player know to 'see' the individual movements within it? That is the job of what is known as an embedded cuesheet, which describes the precise durations for each movement contained 'within' the superFLAC. This way of doing things used to have a lot of benefits, as it could ensure true gapless playback (i.e., where movements play continuously or start abruptly immediately the previous one ends), even when one's choice of music playback software didn't support 'true' gapless playback. These days, most music players can handle the transition between separate FLAC files quite well, so that forcing gaplessness by only having a single superFLAC to play isn't really necessary -but it remains a convenient way of not having too many small files on a hard disk!

Taking one of my own superFLACs as an example, therefore:

This cuesheet tells us that Track 2 of Britten's opera starts at 4:04 from the start of playback; Track 3 starts 7:10 in, and so on. Now, none of that matters to Giocoso anyway, since as I've already mentioned above, it's a 'recording-centric' music player: it either plays the whole of this opera, or it doesn't. It doesn't keep tabs on what track it's playing at any given time and is not aware of what tracks it has already played. It only ever deals with entire recordings (or compositions).

But this then raises the question: when Giocoso completes playback of this opera, what should it scrobble to Should it say 'I played Britten's A Midsummer Night's Dream' -one scrobble, for the entire superFLAC? Or should it say, "I played Introduction...Over hill, over dale, then I played Oberton is passing...Ill-met by moonlight, then I played Well, go thy way...." and so on?

Well, whether it should do one thing or the other, the fact is that Giocoso will scrobble on a per-track basis, even if there's only one physical superFLAC actually being played. The rule about not scrobbling anything at all unless the entire superFLAC is played beginning to end still applies, but if you make it through to the end of a superFLAC, Giocoso will read the embedded cuesheet from that file and will construct 'virtual scrobbles' from it, before submitting them all at once to

The slightly odd side-effect of this way of doing things is that will think you played the entire opera in less than a second... which is oddly impressive! But that's the consequence of a per-track website interfacing with a per-composition or per-recording music player like Giocoso: the clock time assigned by to each and every 'virtual scrobble' will be that which applied when the entire superFLAC completed playback.

Anyway: the short version is that if you elect to use single-FLACs and embedded cuesheets for your music library, Giocoso will happily play the result... and scrobbling to will still be able to take place, too. I will only note in finishing that the cuesheet describing the superFLAC has to be an embedded one -that is, stored within the FLAC file it describes. External cuesheets are never read by Giocoso and therefore the contents of them cannot ever be used as the basis of scrobbling something to

7.0 Conclusion

To sum up:

  • Giocoso needs to be configured to scrobble once (using the --scrobble-config runtime parameter)
  • Giocoso needs to be instructed to scrobble (using the --scrobble runtime parameter or the SCROBBLE=Yes directive in the persistent configuration file)
  • Giocoso will only scrobble when the playback of a complete recording ends
  • Giocoso will scrobble multiple tracks for a single recording, if you store your music physically as one-track-per-movement
  • Giocoso will also scrobble multiple tracks for a single recording, even if you physically store the music in a single physical file, provided that an embedded cuesheet correctly describes the logical contents of the single file
  • Whenever Giocoso scrobbles multiple tracks, the timestamp assigned to all of them will be identical and will be the time that the last track completed playback

[Back to Front Page]|[Adminstrative Runtime Parameters]|[Appearance/Behaviour Runtime Parameters]