The configuration file for the “Observation & Detection” component of the Spy application was initialised by the configuration wizard, but any changes will need to be done manually using the shortcut named “Configuration (MySpy.ini)”
See here for an description of AlbumPlays’ configuration process.
See here for a description of the configuration wizard which created the configuration file
Use the shortcut named “Spy Configuration documentation” for a more detailed description of each configuration option. The main options are:
| Task | Option name and function | Ini Section |
|---|---|---|
| Listener settings | ||
| List of tracked Listeners | _lfm_id_list | detect_spy |
| Assign zones to Listeners | _lfm_id_zones | detect_spy |
| Define the default Listener | _lfm_zone_default_id | detect_spy |
| Transfer Directory | ||
| Default path for inter-component comms | _nas_path | sonos_observer |
| Linux only: use if the above path is local to your Linux device | _nas_path_is_local | sonos_observer |
| Spy Transfer Options | ||
| Path for optional transfer db | _database | detect_spy |
| Turn off db transfer option | _suppress_out_db | detect_spy |
| Path for option Spy text file | _spy_text_directory | detect_spy |
| Turn on text transfer option | _out_text | detect_spy |
| Don’t move text file to _nas_path | _suppress_move_txt_export | detect_spy |
| Communications Port | ||
| Override the LAN communications port | _listening_port | sonos_observer |
| Sending ALERT emails | _email_server_credentials_encryption_key | detect_spy |
| Others | ||
| Set Spy component into debug mode | _debug | sonos_observer |
Listeners
see here for an overview of AlbumPlays’ multi-listener facilities
There are further details in places linked to above, but in summary, the key requirements are:
- each tracked listener must have a unique ID. The ID may be anything (eg: name, initials, etc). Items in the list are separated by blank spaces. An ID cannot contain an embedded blank character
- each Listener must also be known, by the identical ID, in the main AlbumPlays configuration file. Upper|lower case is significant.
- it can be a good idea to define an ID to cover any untracked Listeners or Guests
- each Listener may be assigned one, or several, or no Sonos zones. A Sonos zone may not be assigned to more than one Listener.
- replace all blanks within zones names with a _ character; eg Family Room becomes Family_Room
- a track played upon an unassigned zone is attributed to the “default” Listener
- depending upon how you use AlbumPlays, the “default” listener can be either the “untracked” listener, or the main listener in the household (yourself presumably)
Here are some examples. In the first configuration, there are 2 Listeners. One Listener is assigned a zone, and the other Listener will be assigned the remainder of the household’s zones due to the _lfm_zone_default option. Listener AKM should start her listening session 1 in the Studio, and all other plays will be attributed to Listener BJM
[sonos_observer]
[detect_spy]
_lfm_id_list=BJM AKM
_lfm_id_zones=studio:AKM
_lfm_zone_default_id=BJM
In this second example there are the same two Listeners, and a catch-all Listener ID has also been registered for non-tracked plays. Listener AKM has been assigned a zone, and Listener BJM two zones. Both Listeners should begin their listening sessions at one of their assigned zones. Any other use of the Sonos equipment will be assigned to the catch-all, and the main AlbumPlays module can then be configured to auto-ignore these plays.
[sonos_observer]
[detect_spy]
_lfm_id_list=BJM AKM ignore
_lfm_id_zones=studio:AKM office:BJM family_room:BJM
_lfm_zone_default_id=ignore
Transfer Directory
“Transfer” refers to sending information from this “Observation & Detection” (aka O&D) component, to the main AlbumPlays Play Count component (which then uses the Spy observations to update Last.fm, and for optional scrobble to Last.fm).
When reading the following, remember that AlbumPlays allows for the option of running this O&D component on a seperate computer to that running the main AlbumPlays component. Also the O&D computer may be a cheap Linux device without either keyboard or screen. The transfer settings are required to handle these options.
A common directory needs to be available to both components, and both need to be able to update that directory. If the two components are running on separate computers a NAS or Server is the best location for this folder. The directory needs to exist; AlbumPlays will not create it for you.
This O&D component will use the transfer directory as follows:
- store a html menu so that you can control the O&D component from a browser running on your main Windows computer
- a location where the O&D component can export its log file to, so that you see what is happening when looking from your main Windows computer
- a local location to store the optional transfer database, used to receive the Spy track play observations
- and an export location for the optional text transfer file of Spy observations, when sending them to your main computer
Define the path to this shared directory using the _nas_path option:
- this option is recommended, but it is optional
- if this option is not explicitly specified, it will default to AlbumPlays’ working directory (Linux: /home/pi/.local/sonos_spy; Windows: C:\Users\
\AppData\Roaming\Python\sonos_spy) - if the path begins with a ~ character it will be replaced by your home directory
- Linux: if you follow the recommendation, you will place the path outside your Linix device, in which case this option will point to your Linux mount point
- Linux: if you need your nas_path to be a local path on your Linux computer, you must also specify option _nas_path_is_local otherwise Spy will throw an error, as it will not see the path as being mounted.
Spy transfer options
This section specifically refers to transfering track play observations from this Spy “Observation & Detection” component, to the main AlbumPlays component.
There are two Spy transfer options:
- via a transfer database
- via an exported text file
They were discussed here during the Spy module installation step. … Recap:
- database transfer is the recommended option
-
it is also recommended that you use the text file transfer as a backup to the database option
-
the _database config entry is required unless db transfer is suppressed via option _suppress_out_db.
The _database config entry describes the location of the transfer database. This can either:
- just a file name (in which case the database file will be stored at the path described by _nas_path)
- or a path (including file name) relative to _nas_path entry … nb: no leading slash
- or an absolute path for the database file … (start the path with a slash)
The optional text transfer conduit is selected during the Spy installation task, otherwise you need to manually set it on via the out_text option. You specify the file location via the _spy_text_directory option. You should set this location to a directory local to the Spy Observe & Detect component, as a precaution against any communication issue with your network drive. When it is “Exported” it will be relocated to the path specified by the _nas_path option, unless option _suppress_move_txt_export is specified.
The _scrobble_text_directory option can be:
- or an absolute directory path (recommended)
- or a directory path relative to the path in option _nas_path
important: Any directories specified in the _nas_path, _database, or _spy_text_directory entries must pre-exist, ie. AlbumPlays will not create them for you
Here are some configuration examples. The first example illustrates the recommended situation, where this component is running on a Linux computer. Both transfer options are selected (the text file explicitly, and the database implicitly as it is has not been turned off via the _suppress_out_db option). The database is being written to the NAS location specified in a Linux mount point defined at /mnt/nas. The text file is being written to a directory on the Linux desktop, and when exported will be written the NAS directory specified in the Linux mount point.
[sonos_observer]
_nas_path=/mnt/nas
[detect_spy]
_out_text=Y
_database=spy.db
_spy_text_directory=/home/pi/Desktop/Temp/
This second example shows a situation where this component is running on a Windows computer, and it writes its transfer information to a NAS share. Both transfer options are selected. The database is in a sub-directory named “database” of the NAS share (you need to create this sub-directory manually). The text file will be given a default name, and will be accumulated in AlbumPlays’ working directory, and when exported will be written the NAS directory specified in _nas_path.
[sonos_observer]
_nas_path=//MyNAS/some_share/
[detect_spy]
_out_text=Y
_database=database\Spy.db
In next example this component is running on a Windows computer where there is no NAS. Both transfer options are selected. The transfer database is stored in the standard location used by Windows Vista and beyond, for application data (ie. a directory for AlbumPlays in your profile’s Appdata\Roaming “special” folder). The text file of Spy observations will be accumulated in an AlbumPlays\Spy directory within your My Documents folder, and while the Export step is still required, the exported file will remain at that same location.
[sonos_observer]
_nas_path=~\AppData\Roaming\AlbumPlays
[detect_spy]
_database=AlbumPlays_Spy.db
_spy_text_directory=~\My Documents\AlbumPlays\Spy
_out_text=Y
_suppress_move_txt_export=Y
In the final example this component is running on a Linux computer. Both transfer options are selected, and both are stored locally on the Linux device. The database is stored at AlbumPlays’ working directory (/home/pi/.local/sonos_spy). The text file is being written to a directory on the Linux desktop, and when exported will be written the NAS directory specified in the Linux mount point.
[sonos_observer]
[detect_spy]
_out_text=Y
_database=spy.db
_nas_path_is_local = Y
_spy_text_directory=/home/pi/Desktop/Temp/
See the Quick Start guide for some worked examples showing paired configuration files for each AlbumPlays component, and how they relate to each other.
Communications port
The Observe & Detection component requires a network port for communication with your Sonos zones, and for communication with the browser based Spy Control Menu.
By default a random port is acquired. This will speed up attachment to your Sonos zones if O&D module is being restarted following an abnormal termination. But if you want to open just one port in your firewall, you can optionally override by specifying a static network port for AlbumPlays to use. Specify a port within the IANA Ephemeral port range (between 49152 & 65535).
[sonos_observer]
_listening_port=53893
Alert emails
The device running the Spy O&D module can be configured to send you Alert emails if a problem arises which interfers with the collection of track play observations. This is useful if the device is unattended or has no screen.
nb: alert message are available only where you have used the transfer database option
The option for Alert Email messages relies upon you configuring the Playcount module with email credentials as described here
You then need to sync the credentials to the Spy Transfer database, as displayed below:
The stored email credentials are encrypted, and you usually need to resupply the encryption phrase each the credentials are used. … This requirement needs to be relaxed if you want to send Alert email messages, as the device is presumed to be unattended. … You have to supply your encryption phrase to this Spy module, so that the alert email can be sent without requiring assistance. This done via the following configuration setting:
[detect_spy]
_email_server_credentials_encryption_key=xxxxx
An alert email is also sent each time the Spy O&D component is started or terminated. Verify that you get the starting email, so that you can be sure that the alert email facility is configured correctly.