1.0 Introduction
Giocoso Version 2 introduces the concept of separate source and destination databases. That is, the source database is a permanent store of where, physically, music files exist on your hard disk, whilst the destination database is a permanent store of what music has been played and when. If you get Giocoso to use the source database to decide on what music to play next, you're running Giocoso in Database Play Mode. If you instead tell Giocoso specifically what music to play next, providing your own details about the physical location of those music files, then you are not using a source database at all and are instead running Giocoso in Direct Play Mode.
If you run Giocoso in Database Play Mode, all completed plays of music are always stored in the same database as was used to source the plays in the first place. That is, in Database Play Mode, source and destination database are always (and irrevocably) the same. You do not need to specify a destination database in Database Play Mode (and it's ignored if you try anyway!)
On the other hand, if you run Giocoso in Direct Play Mode, then whilst there is no source database, you can nevertheless ask Giocoso to store the history of its plays in a destination database, specified by the runtime parameter --destbd=xxxx. You don't have to do this, though: if you don't specify a --destdb runtime parameter when launching Giocoso in Direct Play Mode, then there will be no local history of plays kept -though, if you've configured scrobbling to happen, plays will still be recorded remotely at Last.fm.
Giocoso's default mode of operation is to run in Database Play Mode. If you want to run it in Direct Play Mode, you need to invoke it explicitly in a number of ways, as documented below.
You also do not need to run Giocoso exclusively in one play mode or the other: it's perfectly legitimate to have a source database which you use most of the time (i.e., run in database play mode most of the time) and then decide, for whatever reason, that you want to direct Giocoso to play the next few recordings directly (i.e., in direct play mode). You can switch back and forth between the two modes of sourcing music as often as you like. As a for-example, I routinely play my music in database play mode: I like the randomisation element of surprise which that play mode brings with it. On November 22nd each year, however, I want my music plays to be anything but random: for that is Benjamin Britten's birthday and everything I play that day should be his music. So, for that particular day, I'll direct which plays should take place and ensure that they are all of Britten's music. As another example, I'll also be switching to direct play mode on 12th October 2022, because that day is Ralph Vaughan Williams' 150th birthday.
You get the idea, I hope: use a source database for most days; use direct play mode for special occasions (or moods). If I ensure that my --destdb runtime parameter is set to the same --dbname value I use when running Giocoso in Database Play Mode, I am able to ensure that all my music plays are recorded in a single database, regardless of what play mode I was running in when they were performed.
2.0 Invoking Direct Play Mode
There are three ways of initiating direct play mode:
- change directory to a folder containing at least one FLAC file and launching Giocoso with the runtime parameter --dbname=none (called 'local play')
- launch Giocoso from anywhere you like (even a folder containing no FLACs), specifying --musicdir=/full/path/to/folder/containing/flacs (called 'remote play')
- launch Giocoso from anywhere you like but using --playlist=/full/path/and/filename, instructing Giocoso to read each line of the playlist in turn and play the contents of the folder specified by each line (called 'playlist play')
All of these options require that you state explicitly that there is no source database telling Giocoso where to find music files to play, by using the --dbname=none runtime parameter. Instead, you are telling Giocoso directly where to find music files: by sitting in a folder full of them; by pointing to a folder full of them; or by pointing to a text file which itself contains a list of folders full of them.
In every case, however, you can direct Giocoso to record the details of what music was played by specifying the --destdb=xxxx runtime parameter (where 'xxxx' is the case-sensitive name of a database you've previously created with the --createdb runtime parameter).
No matter how you invoke Direct Play Mode, no selection runtime parameters can be specified (and they are ignored if you do specify them anyway!): you're telling Giocoso precisely what to play, so filtering and restricting things after you've been that specific is a bit redundant! For the same reason, if you ordinarily have an excludes.txt to stop Giocoso from play, say, Gustav Holst randomly, then cd'ing to a folder of Holst's music and running Giocoso from there with the --dbname=none is a specific instruction to play Gustav Holst! It would make no sense to then not play Gustav Holst because he's mentioned in the excludes.txt.
I'll briefly elaborate on each of these three direct play invocation options now.
3.0 Local Play
This technique means physically sitting in a folder of FLACs before you invoke Giocoso with the --dbname=none runtime parameter. No selection parameters can be meaningfully specified, since selections are only ever made by consulting a database; any such parameters that are supplied are simply ignored. If you specify a valid --destdb parameter, however, then the fact of the play will be recorded in the destination database once the play completes.
By way of example, assume I have a folder of music called /sourcedata/music/classical/B/Benjamin Britten/Choral/Corpus Christi Carol (Hahessy - 1961)/. Therefore, I can launch Giocoso in local direct play mode by issuing the commands:
cd "/sourcedata/music/classical/B/Benjamin Britten/Choral/Corpus Christi Carol (Hahessy - 1961)"
giocoso --dbname=none --selections=1
I had to wrap the folder name within double quotes, of course, because the spaces some parts of the path contain would otherwise break things. That detail aside, I'm simply using the 'cd' command as you would normally, to navigate my way through my file system to a folder in which I know one or more FLAC files exist. The "selections" runtime parameter I added to the basic 'giocoso' command is optional, of course: without it, however, the number of selections would kick in from the persistent configuration file -and if that happens to be set to, say, 16, then this one piece of music would be played 16 times in a row, which is probably not a great idea! Here's what Giocoso looks like as the music plays:
The program display looks pretty much as it always does. The only real giveaway is in the third line of green text at the top of the screen: "Direct Play Mode (local)". Otherwise, you'll note the timebar doesn't apply (it makes no sense to bar the playing of certain composers because they have been played recently when you are specifically directing a specific piece of music be played). The bottom status/counter line is exactly as it would be, too, in any other play mode.
When playback has finished, this happens:
You will note that scrobbling takes place perfectly normally: direct play does not stop Giocoso sending play details to Last.fm, provided only that scrobbling has been (a) configured and (b) requested. In this case, I didn't request scrobbling on the command line -but the parameter is switched on in my persistent configuration file, so I got a scrobble anyway. Scrobbling once configured in the persistent configuration file cannot be switched off (unless you edit the configuration file, of course), because there's no "noscrobble" runtime parameter to over-ride the configuration file setting.
What you don't see in that last screenshot, however, is any sort of notification to the effect that 'the play is being recorded in a database' -because I chose not to specify the --destdb runtime parameter. Let me re-launch Giocoso with this command, however:
giocoso --dbname=none --selections=1 --destdb=main
You will notice nothing at all different about the program display as the music is played, despite the extra parameter in use. However, once the play completes, we see this output:
The difference is very slight, but it's there: "Recording play in database" is displayed, indicating that not only has Giocoso scrobbled the fact of the play to Last.fm, it's also recorded it within the "main" database, which was the name I supplied to the --destdb runtime parameter.
Incidentally, if you specify a destination database that doesn't actually exist, you'll see this by way of response:
Remember that parameter values are generally case-sensitive, so a database called 'main' is different from one called 'Main' or 'MAIN'. In this case, by bolting a '2' onto the end of the database name, I've literally specified a database that doesn't exist. Destination databases have to be created ahead of time as part of a music collection scan (i.e., they are also capable of acting as source databases).
You do not have to record a direct play in a destination database; you also don't have to scrobble it, if you prefer not to. The --destdb and --scrobble runtime parameters are there to be used if you want to, but are not compulsory.
Finally, you will perhaps realise that this mode of direct play can only ever trigger the playback of a single folder-full of music files. There's no way in local mode to say 'play this, then that, then this other thing'. To achieve that, you'd have to 'cd this', play, 'cd that', play, 'cd this other thing', play. Giocoso in this mode is only looking at the contents of the folder it was launched in and has no knowledge of any other folder or music files, therefore.
4.0 Remote Play
Having to change directory all the time before invoking a direct play can be inconvenient: it's potentially a lot of typing and is taking you away from whatever folder you were already in. If you were there for good reasons, those reasons fly out the window the minute you cd away! Fortunately, you can instead launch Giocoso in 'remote direct play mode', by staying where you are and providing a --musicdir parameter to tell Giocoso where the music you want played exists.
The parameter takes the name of a folder as its argument, not the name of a specific FLAC file: remember, Giocoso plays folders, not files!
To play the same music as I did back in section 3 above, therefore, I could simply issue these commands:
cd /home/hjr
giocoso --dbname=none --musicdir="/sourcedata/music/classical/B/Benjamin Britten/Choral/Corpus Christi Carol (Hahessy - 1961)" --selections=1
The first 'cd' command there is just to emphasise the point that I can be sitting anywhere in my file system and nevertheless get music played from a completely different folder:
Again, the main program display gives no particular clues that Giocoso is operating in any particular playback mode, except for the third line of green text at the top of the screen, which does mention 'Direct Play Mode (remote)' now.
As with direct play local mode, you will get scrobbling happening at the end of the play, if it's configured and if you ask for it; and if you specify a valid --destdb runtime parameter, the fact of the remote direct play will be recorded in a database:
The 'recording play in database' message is the only indication you get that a destination database was specified.
Just as with direct play local mode, too, you cannot specify more than one folder to play when launching Giocoso. It's not possible to say, 'play this, then that'. If you specify the --musicdir parameter twice, for example, only the second one 'counts'. For example, here's what happens when I submit this crazy command:
giocoso --dbname=none --musicdir="/sourcedata/music/classical/B/Benjamin Britten/Choral/Corpus Christi Carol (Hahessy - 1961)" --musicdir="/sourcedata/music/classical/G/Gustav Holst/Choral/A Choral Fantasia (Wetton - 1993)/"
I got Holst, not Britten, because the Holst folder was the last folder listed.
5.0 Playlist Play
New to Giocoso Version 2, the --playlist parameter allows us to point Giocoso not to a folder full of music files, but to a text file which itself lists a lot of folders full of music files! Here, for example, are the contents of a file I have sitting on my desktop:
As you see, it's just a list of folders, one folder per line. Nothing is enclosed in double quotes, even though the folder names have plenty of spaces within them. Having prepared this file (precisely how you type all this stuff in without making a typo, I leave as an exercise to the reader!), I can now invoke Giocoso with this command:
giocoso --dbname=none --playlist=/home/hjr/Desktop/subminute.txt
...and this happens:
Note the third line of green text at the top of the display: 'Direct Play Mode (from playlist)' tells you that you are now, indeed, driving music plays from a playlist. As one piece comes to an end, here's what happens:
You will note that playlist plays can be scrobbled, just like in any other direct play mode, provided only that scrobbling has been configured and enabled. The other thing to spot this time, however, is that message about 'Pausing between plays for 5 seconds'. This tells you that Giocoso is making multiple plays, because the playlist I pointed it to itself contains a list of multiple folder names. This is therefore the only Direct Play mode that permits multiple plays from multiple folders in one play 'session' (the other two modes, as we have seen, is strictly 'play this folder, relaunch to play a different folder' and so on). The length of time for the 'pause between plays' is governed by the --pause=x runtime parameter, where 'x' is a number of seconds greater than or equal to 0. This command:
giocoso --dbname=none --playlist=/home/hjr/Desktop/subminute.txt --pause=99
...produces this result, therefore:
...which, incidentally, tells you it took me 15 seconds to capture the screenshot properly! The number of seconds in blue counts backwards down to zero.
There is no variation in the way Giocoso plays through a playlist. It starts at the top and works its way through one folder at a time until it reaches the bottom. The ordering can't be varied or changed, except by editing and re-arranging the contents of the playlist itself. You can, however, issue the command giocoso --skip from a second terminal session to trigger a jump to the next folder listed in the playlist. You can similarly issue the command giocoso --autostop in a second terminal to make the playing session terminate all play when the currently-playing folder has finished.
Should a line in a playlist contain an error, this will happen:
As you know, Giocoso plays folders and the playlist is just a list of folders: as soon as it mentions a folder which physically doesn't exist on disk, all further playback is terminated. Giocoso won't just skip over the mistaken entry and play the next valid folder, in other words.
Be warned that the --selections runtime parameter applies to the entire playlist. If it's set to 9, as you can see from the above screenshots it has been, then I shall hear the same list of more than 30 recordings played 9 times in succession. It doesn't mean each folder gets played nine times before moving on to the next row in the playlist, for example.
As with all the Direct Play options, you can add a --destdb runtime parameter to the invoking command so that plays are recorded within a local database. It is, of course, optional to specify such a destination database.
5.1 Generating a Playlist
I said earlier that I'd leave working out how to create a flawless playlist as an exercise for the reader... but I figured I should show you two possible ways of doing it, anyway! First, the command line way, if all the potential folders you want to play are accessible from a 'parent' folder in your file system hierarchy. For example: let's say I want to create a playlist of all Benjamin Britten's operas. In that case, I can do the following:
cd "/sourcedata/music/classical/B/Benjamin Britten/Opera"
ls -d "$PWD"/*
That produces a folder listing like this:
You'll notice that the file 'Opera.jpg' has managed to get included on that list, which is a problem, but not a show-stopping one. Rather more significantly, of course, that's just a folder list on-screen, not a playlist! Fortunately, re-direction helps. If the last command above is actually this:
ls -d "$PWD"/* > /home/hjr/Desktop/BenjaminBrittenOperas.txt
...then now I have a proper playlist on my desktop. It is then trivial to open it up in a text editor, remove any lines that refer to things which aren't folders of music and maybe move lines around to knock the playback order into shape.
The second technique I thought was worth mentioning was the use of a tool such as DB Browser for SQLite. That's a free tool that allows you to query the Giocoso source database and construct resultsets which match all sorts of criteria you might think of. Here's an example of what's possible:
Note that the querying language used here permits wild-carding, filtering and selecting by all sorts of criteria, including the length of each recording (measured in seconds), and so on. With an 'order by' clause, you can also order the rows returned by the query into any desired ordering. Once you can see a resultset such as this, it's then trivial to highlight the 'dirname' column and copy that into a text file... and that's your new playlist.
SQL is not for the faint-hearted, I will readily concede! But the capability exists and it's only a matter of practice to get it right.
6.0 Conclusion
So now you have seen three different ways of telling Giocoso precisely what to play -and understood that it's possible both to scrobble and to store locally the fact of such directed plays. Direct Play Mode is not Giocoso's default mode of operation, because it's fairly inflexible and cumbersome to use. But it has its moments!
Whilst you might be happy to use a source database for day-to-day, randomised music play, special days or events might cause you to want to be more in control of what Giocoso plays and in what order -and that's what Direct Play Mode is good at. When it comes to celebrating Benjamin Britten Day, for example, I always have a special Benjamin Britten playlist on hand, so that I can enjoy a handpicked selection of only his music for the day... but on most other days, Dataabase Play Mode is what I rely on.