rapblock/README.md

RapBlock
========

This is a daemon that auto-skips rap and hip-hop songs on Spotify via MPRIS.

Music genre is determined using the MusicBrainz JSON API, as that is not reported via MPRIS.

Compatibility
-------------

This daemon should work with any MPRIS compatible player, so long as it reports artist names 
in the TrackChanged event metadata.

Customization
-------------

The daemon loads its config from a JSON file, an example of which is provided as 
`rapblock.example.json`. Copy this file (removing `.example`) and customize as desired.

Defaults will be loaded in absence of the config file.

Here is the structure explained (please note that JSON doesn't allow comments,
this is just for the demonstration):

```
{  
  // Blacklist config
  "blacklist": {
    // Literal tags to reject
    "tag": [],    
    // Tag sub-strings to reject (must be a whole word)
    "tag_partial": ["hip-hop", "hip hop", "rap"],    
    // Artists to reject without even checking tags
    "artist": ["Higher Brothers"]
  },    
  // Whitelist config
  "whitelist": {
    // Tags to allow despite e.g. a substring match
    "tag": [],    
    // Artists to allow unconditionally
    "artist": []
  },  
  // Logging - trace, debug, (info), warning, error
  // Set to "debug" for more detailed logging (e.g. to see the received
  // JSON, or the parsed config file) 
  "logging": "info",  
  // Player names to allow (e.g. when we want to block only Spotify songs).
  // This does not support multiple players playing at once - always only
  //  the first is handled.
  "allowed_players": [
    // spotify player name, as copied from the debug log
    // -> Leave this list empty to allow all players!
    "org.mpris.MediaPlayer2.spotify"
  ],  
  // Min MusicBrainz search score for artist look-up
  "artist_min_score": 95,  
  // Max nr of artists to check per track (limits MusicBrainz request count)
  "max_artists_per_track": 3,  
  // Interval in which the daemon probes DBUS for open MPRIS channels
  "player_find_interval_ms": 2500,  
  // Delay after a skip or allow, e.g. to prevent infinite skip chain
  // when someone starts a rap playlist and we block the 'rap' tag
  "cooldown_ms": 500,  
  // Music Brainz API access timeout
  "api_timeout_ms": 2000,  
  // Action to take when the daemon can't figure out if a song is good or not.
  // Default is true; change to false if you REALLY hate rap, but it will 
  // also block good songs by less known artists.
  "allow_by_default": true
}
```