Configuration – Spy – Observe & Detect

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 the application’s 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
List of tracked Listeners _lfm_id_list
Assign zones to Listeners _lfm_id_zones
Define the default Listener _lfm_zone_default_id
Turn on text transfer option _out_text
Default path for inter-component comms _nas_path
Path for optional transfer db _database
Turn off db transfer option _suppress_out_db
Path for option Spy text file _spy_text_directory
Don’t move text file to _nas_path _suppress_move_txt_export
Override the LAN communications port _listening_port

Listeners

see here for an overview of this application’s 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 this application, 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 application 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

“Transfer” refers to sending information from this (“Observation & Detection”) component, to the main AlbumPlays Play Count component (ie. uses Spy observations to update Last.fm, and for optional scrobble to Last.fm).

When reading the following, remember that this application allows for the option of running this Observe & Detect component on a seperate computer to that running the main AlbumPlays component. Also the O&D computer may be a cheap Linux device without a keyboard or screen. It is because the two components are designed to run at an arm’s length from each that these transfer facilities are required.

A directory needs to available to both applications. Both applications need to be able to update the directory. If the two components are running on seperate computers a NAS or Server is best for this.

This “Observation & Detection” component will use the transfer directory as follows:

  • store a html menu so that you can control it using a browser running on your main Windows computer
  • a location where that this component can export its log file to, so that you see what is happening when looking from your main Windows computer
  • a location to store the optional transfer database, used to receive the Spy track play observations
  • an export location for the optional text transfer file of Spy observations

Define the path to this shared directory using the _nas_path option.

Spy transfer options

“Transfer” here refers specifically to sending track play observations from this component (“Observation & Detection”), to the main AlbumPlays component.

There are two Spy transfer options:

  • via a transfer database
  • via an exported text file

They were discussed here earlier.

Recap:

  • database transfer is the recommended option
  • it is also recommended that you use the text file 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. It can be:

    • just a file name (in which case it will reside at the path described by _nas_path)
    • or a path relative to _nas_path entry … don’t start the path with a slash … you must include the file name for the database
    • or an absolute path for the database file (start the path with a slash)
  • the _spy_text_directory defines where the optional Spy text file is accumulated. It should be set to a directory local to the 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
  • any directories specified in the _nas_path, _database, or _spy_text_directory entries must pre-exist, ie. this application will not create them for you

Here are some configuration examples. The first example illustrates a 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=BM_pi.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 “database” sub-directory of the NAS share. The text file will accumulated in the application’s 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 this final 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 the application 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

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 the appliucation to use. Specify a port within the IANA Ephemeral port range (between 49152 & 65535).

[sonos_observer]
_listening_port=53893

  1. a “listening session” is defined here