1.0 The Giocoso Menu Interface
Giocoso version 2.01 introduces an entirely new (and optional!) way to interact with and control the program: a menu interface. It consists of a simple screen of numbered options that you can take to achieve particular outcomes:
All these options are simply new ways of achieving what, in earlier Giocoso versions, would have been possible only by constructing potentially lengthy and typo-prone command line sequences of runtime parameters. To autostop in Giocoso version 2.0, for example, you'd have to open a new terminal and type giocoso --autostop. To re-display album art, you'd again have had to open a new terminal and type giocoso --artwork. With the new menu interface, you simply type '5 -> Enter' or '8 -> Enter' to achieve the same results, respectively.
In the same way, whereas in Giocoso version 2.0 you might have issued the command giocoso --composer=britten --composition=grimes --comment=britten, you can now take option 2 and fill in the prompts like so:
The result will be the same in either case, but the one is perhaps considerably simpler to type and use than the other!
Giocoso still needs to be told how to behave: how big your computer monitor is; how to colour the album art caption panel; whether to use a database as source of things to play, and if so what it's name is; and so on. With the traditional ('complex'!) Giocoso interface, you told the program those things by specifying a raft of runtime parameters (such as --dbname, or --smartcolour, for example). When you use the new menu interface, however, there's no ability to pass such runtime parameters to the program. Such configuration details have therefore to be supplied by parameters set in the persistent configuration file. That was invented in Giocoso version 2.0 precisely with this future menu interface capability in mind -but it now becomes the primary way to tell Giocoso run in menu-mode how to behave, rather than an optional extra as it was in version 2.0.
To use Giocoso via the new menu interface, you launch the program with the new --menu runtime parameter. The basic command to launch Giocoso in this way thus becomes: giocoso --menu, with no other runtime parameters specified (they're ignored if present, anyway!)
The menu interface runs independently of any Giocoso session that may be playing music. That is, if you launch Giocoso with the --menu runtime parameter in one terminal, the menu will persistently display until you explicitly take the quit option. We therefore start referring to 'the Giocoso menu session' and the 'Giocoso playing session'. The two are quite distinct in form and function.
The menu session may spawn other terminals that play music: that's what options 1, 2 and 3 do, after all; but those 'playing sessions' will be running independently of the menu interface. That means you can quit and re-launch the menu interface as often as you like whilst music continues to play in those other terminal sessions.
As an example: I run the command giocoso --menu in a new terminal session. I then take Option 1: I now have a second terminal session playing music. I can then type 'q' in the first session to quit the menu interface: the music playing session will continue to run until its natural end. Before it has reached that 'natural end', I can then re-run the giocoso --menu command and 'q'uit from it as many times as I like: the music playing terminal will still continue to run to its natural end.
Now to step through each group of menu options in some detail...
2.0 Play Options
Option 1: Play music in Giocoso using defaults. This option will use the persistent configuration file to determine what settings/filters to apply to music selection. If you have set MINDURATION=20 in the configuration file, for example, then Giocoso will only select to play recordings that last longer than 20 minutes. The database used to source the 'plays' will be that specified by SOURCEDB in the configuration file, and so on. The 'defaults' spoken of in the menu option text are, therefore, configured defaults. When Option 1 is taken, a new minimally-sized play window will be opened in which the progress of the music plays will be displayed:
This display is deliberately minimal and is used to perform all music plays produced by taking any of Options 1, 2 or 3. See below for further details of this new minimal play window.
Option 2: Play music in Giocoso with filters. There are no options in the persistent configuration file for specifying particular composers, compositions, genres or performers (having to edit a text file before you could say 'play me some Beethoven' or 'play me a ballet' would be a clunky way of making such selections, after all!) Therefore, using Option 1 to play music means not filtering music selections by any of those sorts of criteria. Option 2 therefore fills this particular gap: taking it will display a screen in which you are prompted to supply a composer name (or part thereof), a composition name (or part thereof), a genre or a performer name (ditto for both). You don't have to fill in anything for all four prompts: just press [Enter] to leave blank any filter you're not currently interested in applying to your music selections. Whatever you type in will be applied in a case-insensitive manner (so typing 'britten' or 'BRITTEN' or 'bRiTtEn' for a composer name will produce the same outcome). Your entries will also be wild-carded (so 'Bri' will match Benjamin Britten and Frank Bridge equally well, for example; the entry 'grimes' for a composition name will similarly match the opera 'Peter Grimes' or the recording of the 'Four Sea Interludes from Peter Grimes').
Option 3: Resume a Giocoso Play Session. A new feature of Giocoso version 2.01 is that, if you press Ctrl+C to kill off a Giocoso playing session, you can subsequently resume the playback of the recording you interrupted by taking Option 3 from the menu session. (The same effect can be had without the menu by launching a new Giocoso session with the --resume runtime parameter). You need to have killed off a playing Giocoso session with Ctrl+C for it to work, however. If you merely close down a playing session by clicking the 'X' close button in its title bar, that doesn't enable the resume functionality.
Option 4: Request a repeat of the current play. Another new feature in Giocoso version 2.01 is that, whilst some piece of music is playing, you can request Giocoso to repeat it once it has completed its initial play by taking Option 4 from the menu session. (The same effect can be had without the menu by launching a new Giocoso session with the --repeat runtime parameter). The option acts like a toggle switch: if you take Option 4 a second time, whilst the initial play has not yet concluded, you will be revoking the repeat request. Take the same option a third time, however, again before the initial play has concluded, and you are re-instating the repeat request. The repeat play of a recording does not increment the plays count (so if you asked to repeat the 3rd of 9 possible 'plays', at the end of your entire 'play session' you would end up having heard 10 plays, with one recording played twice).
3.0 Messaging Options
Giocoso has long been able to use one session to 'send messages' to another, separate playing Giocoso session, to alter its behaviour. In Giocoso version 2.0, for example, you could open a new terminal and issue the command giocoso --autostop, and this would be a message sent to another playing Giocoso session to cease playing further recordings once the current recording had reached its natural conclusion. Options 4 to 8 in the new Giocoso menu interface allow you to send such messages to a separate playing session merely by typing the appropriate menu option number.
Option 5: Toggle Autostop. As just mentioned, Autostop is the message that instructs a music-playing Giocoso session to let the current recording complete and then not to play any further recordings, even though the original session was configured to play (say) 9 recordings in succession and it's only on play number 2. Autostop is a toggle: take Option 4 once and Autostop is enabled; take it again and it is disabled; take it a third time and Autostop will be enabled again... and so on.
Option 6: Skip a recording. Using this menu option, you can instruct a playing Giocoso session to immediately terminate whatever it's currently playing and (assuming sufficient selections remain before program termination) to begin playing whatever the next music selection might be.
7: Terminate all plays. This option is unique to the menu interface. It simply issues both an Autostop message and a Skip recording one. This means you've asked to 'not play anything after the currently-playing recording finishes' and 'please immediate terminate the currently-playing recording': the net effect is that all music playback instantly terminates.
8. Re-display album art. This messaging option means you can instruct a playing Giocoso session to re-display the album art panel associated with the currently-playing recording. The original panel may have been closed in error, or merely hidden under a pile of other open windows. Taking Option 8 will immediately re-display the panel and give it focus, so that it appears on top of any other open windows.
4.0 Reporting Options
9: Aggregate Statistics. This option displays the one-page summary statistics for your music database, the database providing the information being the one configured as SOURCEDB in the persistent configuration file. Since the statistics report fits within the size constraints of the menu interface itself, taking this option merely displays the report 'within' the same window that the menu itself is displayed within. Just press a key once you have viewed the report to return to the main menu.
10: Recordings. This option is the equivalent of the --recordinglist runtime parameter, which displays a listing of all the recordings of which Giocoso is aware. The twist, however, is that the runtime parameter takes a value of either 'screen' (to display the report on-screen) or 'some path/filename' to output the report contents to a text file. The Option 10 equivalent of this functionality in the menu interface, however, is hard-coded to produce an on-screen version only. If you want the text file report, you can still obtain it, but you'll have to type giocoso --recordinglist=/folder/filename.txt in a new terminal session to get it. Note that the recording report is very wide and cannot therefore fit within the size constraints of the terminal session running the main menu interface. Accordingly, taking Option 10 triggers the launching of a new Xterm terminal, in which the report is displayed. The effect will therefore be something like this:
The report is displayed here in green, in the terminal shown in the lower half of the screen, whilst the menu that launched it continues to be displayed above it. Note that on-screen reports are displayed via the less utility, which means you can scroll up and down through the report in either direction and can just type the letter q to close the report. This means you can also search within the report: if you wanted to find recordings of Peter Grimes, for example, you could type /Grimes at the bottom of the screen and press [Enter]:
You can see how the word 'Grimes' has been found within the report, some 2400+ rows within it, and the word has been highlighted. The text matching is 'optimistic', though, so that selection would also match a recording of the 'Grimesthorpe Colliery Band', for example!
11: Plays. This menu option is the equivalent of running Giocoso with the --report runtime parameter, which produces a listing of everything that has ever been played and recorded within the Giocoso database. Again, the twist is that the --report parameter takes the values of '=screen' or '=/path/filename', whereas Option 11 taken from within the menu interface is hard-coded only to produce a screen version of the report. The text version can still be obtained by typing giocoso --report="/path/filename.txt" in a new terminal session, of course. The Plays report is even wider than the recordings report mentioned earlier, so again: the menu interface will display it in a new Xterm terminal session opened specially for the occasion:
Again, it's displayed via the less program, so scrolling up and down, or searching within the report, are all straightforward to do. Type q to close the report window and return to the main menu display.
5.0 Administration Options
These options allow you to edit important program-related text files, delete various locks, display the program license or administer the Giocoso database in various ways. When any of the administrative menu options are taken, a new sub-menu will be displayed, containing further options. In what follows, these sub-menu selections will be indicated in the form "11/3", for example, meaning 'main menu option 11, followed by sub-menu option 3'.
Option 12: Edit text files. There are two text files which affect the way Giocoso behaves: the excludes.txt (which is optional, but can contain the names of composers whose music you do not want, persistently, to be selected for random playback, for whatever reason); and the giocoso.conf persistent configuration file, which contains (at the time of writing!) 27 different parameters and their associated values, all of which directly affect what music Giocoso will play, how it will play it, and how the program will look as it runs. Taking an option to edit one of these files will open it in whatever text editor is configured to be your systems' default. Often, that's vi, but some distros default to it being nano (which your author finds a lot easier to use!) Altering the editor used will require setting the EDITOR environment variable in whichever way your operating system or distro lets you (often, it's done by editing the $HOME/.bashrc file).
Option 12/1: Edit the Excludes file. The excludes.txt file lists composers, one name per line, that you definitely do not want selected for random play. The names have to be exact matches for what music files have been given in their ARTIST tag: there is no wild-carding nor case-insensitivity involved. Editing the file can be done manually by visiting $HOME/.local/share/giocoso and opening excludes.txt in whatever text editor you fancy. In Giocoso version 2.0, it was possible to edit the file by running the command giocoso --editx. The new menu interface achieves exactly the same outcome with options 12/1. Once any changes have been made, the file should be saved using your chosen editor's standard file->save options. When the file is saved, control will automatically return to the file editing sub-menu. Type 'b' and [Enter] to get back to the main menu.
Option 12/2: Edit the Persistent Configuration File. The giocoso.conf file lists two dozen or so parameters, with associated values, that control the behaviour and appearance of the entire Giocoso program. Editing it means that the program behaviour or appearance will change the next time it is run. Changes are not adopted dynamically by pre-existing sessions.
Option 12/3: Obtain a default Persistent Configuration File. From time to time, as new Giocoso versions are released, the persistent configuration file will acquire new parameters. For example, in the move from 2.00 to 2.01, the file acquired a new TERMINAL_FONT parameter. You can manually add such new parameters to your existing configuration file if you prefer, but if you fail to do so at all, or do it incorrectly, new functionality in the new version might not work properly (or at all). This menu option therefore (a) copies your existing configuration file to giocoso.conf.bkp (within the $HOME/.local/share/giocoso folder); and (b) downloads a new, default configuration file from this website, which is guaranteed to contain default settings for all parameters.
The effect is to give your Giocoso setup a complete, new and default configuration file. Any customisation of parameters that you had previously applied will, of course, now be lost -but a backup of them will exist in the .conf.bkp file, so with a bit of manual effort with a text editor of your choice, you can recover those customised settings from that backup file and re-apply them to the fresh, default .conf parameter file.
Option 12/4: Force new values to apply. If you press v and [Enter], you will see what all the current persistent configuration file settings means for what music 'qualifies' to be randomly selected for play. If you then use options 12/2 to edit the configuration file (say, to alter the min and max durations allowed), and you save those changes; if you simply press v and [Enter] once more, no changes will be apparent at all in the settings. That's because Giocoso reads the configuration file once only, as it is launched. Edit the file after that and, as just mentioned above, sessions that were running before the changes were made won't know about them. Use options 12/3, therefore, to make the menu interface re-read the configuration file. Press v and [Enter] once more -and now the changed parameters will be making a visible difference to the displayed configuration rules.
Option 13: Updates, remove locks, license. This option gives access to a lot of mundane 'housekeeping' features of the program, as follows:
13/1: Check for Updates. This menu option (and all the other 13/x options) does what it says on the tin! Take it and Giocoso will check the absolutelybaching.com servers to see if a more up-to-date version of the program exists. If one does, you'll be offered the chance to download it and install it, though doing so is optional and will require the use of sudo privileges in any case.
13/2: Display License. Giocoso is licensed under the GNU General Public License version 2. A condition of that license is that a copy of it should be made available to any user wanting to see it. These menu options cause the GNU GPL v2 license text to be displayed. The display is done via the less utility, so you can scroll up and down at will; press q to close the text display and return to the menu.
13/3: Remove Play Lock. When Giocoso starts to play music, it outputs quite a bit of metadata to various files on disk. Were another session to start playing an entirely new piece of music, these files would be over-written by the new session. The first session might eventually start to play a new recording -and then it would over-write the files the second session wrote. In other words, multiple play sessions tread on each others' toes in destructive and unpredictable ways. Giocoso version 2.01 introduced the concept of a play lock to prevent this from happening. Once a session starts playing music, it writes a file to disk whose existence is then an instruction to second and subsequent play sessions to immediately shut themselves down without attempting to play anything. The play lock thus prevents multiple play sessions from interfering with each other. Unfortunately, the play lock can sometimes be left behind (if your PC crashes mid-play, for example) and its continued existence on disk would then prevent any new plays ever being performed by Giocoso! Fortunately, Giocoso provides the giocoso --unlock command to forcibly remove a rogue play lock file. Menu options 13/3 achieve exactly the same thing. There is nothing to stop you removing a play lock at any time, whether out of a sense of devilry or simple curiosity -but doing so when it's not actually required is not a good idea!
13/4: Remove Database Scan Lock. The play lock prevents two playing Giocoso sessions from interfering with each other. For similar reasons, operations which scan for music and re-populate the Giocoso database cannot be allowed to conflict with each other, and thus a database scan lock file is created by any operation that needs exclusive scan rights (such as database creation or refreshes). Once again, it is possible for a computer or program crash to leave behind an 'orphan' scan lock file on disk when it's no longer required. The presence of such an orphan lock file will prevent Giocoso from ever again being able to create or refresh a music database. Giocoso version 2.01 therefore provides the new giocoso --descan command to forcibly remove such orphan scan locks. Menu options 13/4 achieve exactly the same outcome. Again, there's nothing to stop you forcibly removing the scan lock at any time and for any reason -but if you do, you are likely to end up corrupting or wiping your music database (fixable by performing a new, properly-locked, database refresh operation, fortunately).
Option 14: Manage a Database. Much of Giocoso's core functionality depends on there being a database containing details of which music files exist, when any of them were last played, how long each one lasts and so on. Creating and maintaining such a music database therefore becomes quite an important part of making sure Giocoso behaves as intended. All the Option 14 sub-menus provide simple ways to achieve that outcome:
14/1: Create a Database: The menu equivalent of the giocoso --createdb --dbname=xxx --musicdir=/path/to/musicfiles command. Taking this option will generate a prompt for the name of the database you wish to create and, subsequently, the full path to the root of the folder hierarchy that is to be scanned for the presence of FLAC files.
14/2: Perform a Complete Refresh. The menu equivalent of the giocoso --refreshdb --dbname=xxx --musicdir=/path/to/musicfiles command. The entire existing contents of the database's recordings table is wiped (but not its history of plays!) and re-populated completely by taking a fresh look at the specified music folder for the presence of FLACs. This is a lengthy process when a large music collection is involved, because each discovered FLAC must be analysed for tag data and duration in turn. Taking this equivalent menu option will trigger prompts for the name of the database that is to be refreshed and the path to the root of the folder hierarchy that should be scanned for the presence of FLACs.
14/3: Perform a Fast Refresh. This is a new option in Giocoso version 2.01, for which there is no runtime parameter equivalent (i.e., these menu options are the only way of triggering a fast refresh of the Giocoso database). A fast refresh still looks through your entire music folders on disk, but it then only adds to the database those recordings which it knows to be new ones. It doesn't update the metadata about any recordings that it knows already exist in the database. That means this refresh option still takes quite a bit of time to scan music folders for the existence of files, but it doesn't spend hours analysing files it has previously analyzed -and it's that bit of the refresh process which, for a large music collection, can take many hours. Accordingly, a fast refresh should take mere minutes. If you've just ripped and catalogued a new CD acquisition and added the FLACs into your music collection folders, for example, using this option will mean Giocoso will 'see' and be able to play the new acquisition within minutes.
To be clear, however: a fast refresh never updates details about recordings that were already present in the database. So, let's imagine you had a recording called 'Requiem' on disk and, one day, you notice that you inadvertently tagged the ALBUM as being 'Reqquiem'. Giocoso thus knows about a file called Requiem.flac, tagged Reqquiem. You spot the tagging error one day and correct it to 'Requiem'. You now run a fast refresh: the correction to the metadata will not be applied, because it's not a new recording as far as the fast refresh process is concerned. You'd need a complete refresh (Option 14/2) before the metadata correction was applied to the database.
To take a second example: you had a physical file called 'Reqquiem.flac' and you spot the error and change it to be 'Requiem.flac'. The fast refresh will see the newly-named file as a new recording and will add it to the database as such. But the fast refresh never removes existing recordings from the database, so your database will now contain two rows, one for a recording called 'Reqquiem.flac' and one for 'Requiem.flac'. The first no longer exists on disk, of course, but it will take a complete refresh (Option 14/2) for the 'extra' row to be removed from the database.
14/4: Import Plays. If you are installing a new operating system or switching to a new PC, you probably don't want to lose your history of plays made with Giocoso in the process. If you back up your original database (to a USB thumbdrive, perhaps), you can then use option 14/4 to import the plays from that backup into a newly-created database, thereby preserving them and moving them onto your new computing platform. Taking this option will trigger prompts for the path to the source database file (the one on the thumbdrive or other backup location) and the name of the database into which you want the plays history imported.
14/5: Backup a Database. Another menu option that has no runtime parameter equivalent command. You are prompted to supply a database name and a full path to a location where the copy of the database should be written.
14/6: Rebuild indexes. Not an option that should ever really be needed, but for which Giocoso version 2.0 introduced the giocoso --dbname=xxx --reindex command. It is possible (though unlikely!) for the Giocoso database to be corrupted over time and a reindex might help restore it to good health. Should the reindex not resolve a problem, a full database refresh would be the next recommended course of action. Failing even that, creating a completely new database and importing the play history from the original to the new would be the option of last resort.
6.0 Summary of Menu Interface Options
As you can see, most menu options are merely one-for-one substitutes for doing what you have previously been able to do with strings of runtime parameter options tacked on to a 'giocoso' command. The menu interface makes using such options rather easier, however. The price to be paid for this simplicity is that sometimes, subtle variations on the options that you'd be able to invoke with runtime parameters are not available for their menu interface equivalents (such as reports generated via the menu interface being on-screen only and incapable of being written to disk, for example). When the menu interface proves too restrictive in those sorts of situations, of course, the option of typing a 'giocoso --runtime-parameter=xxx' command remains available to be taken.
On the other hand, there are at least two things you can do with the menu interface that have no runtime parameter equivalents at all. Backing up a database and performing a fast refresh of a database are only possible by taking the relevant Menu Option 14 sub-options, for example.
7.0 The Minimal Play Window
To complement the new menu functionality, Giocoso is now able to display details of what's playing in a much smaller window than before:
Compare that with the 'normal' playing interface that has been the standard interface since Giocoso version 1.x days:
You'll notice immediately that the new interface has a much simplified header; it doesn't display 'Now in' or the number of tracks and so on. It's bare-bones stuff, simply listing composer, composition and performers plus a time when playback will finish. The recording year, genre and duration are displayed as a simple one-line piece of text, with the various data components separate by dashes. Instead of occupying a 103x27 terminal window, the bare-bones interface requires only a 55x18 one: it's therefore getting on for around half the size of the 'full' interface you've been used to before now.
This new play interface is termed the minimal play interface and can be launched manually by using the new (in version 2.01 and above) --minimal runtime parameter, regardless of whether you use the menu interface or not. If you are a command-line fan and always launch Giocoso with full-on 'giocoso --dbname=xxx --composer=yyyy' commands, then you can still tack --minimal onto the end of those commands and benefit from the more compact display.
The minimal play interface is, however, the only playing interface available when using the new menu interface. If you want to see the 'full-sized' play window, you need to invoke Giocoso in the way you did in version 2 and prior, relying on runtime parameters and the persistent configuration file to configure the program's behaviours.
8.0 Conclusion
Summing up, therefore:
- The new menu interface helps you bend Giocoso to your will without having to type an essay's-worth of runtime parameters! It remains, however, entirely optional: those runtime parameters are still there, still capable of being invoked directly if you prefer to do things that way.
- The new minimal play window is a corollary of running Giocoso via the new menu interface, but can also be invoked directly with the --minimal runtime parameter independently of using the menu interface.