Smart Playlists

Smart playlists populate themselves automatically based on rules you define. Instead of manually adding tracks, you describe the kind of music you want and brūhi builds the list from your library.

[Screenshot: Smart Playlist rule builder — condition groups, Hard/Soft toggle, field selector, operator, value, sort options, limit controls]

Creating a Smart Playlist

1. Open the Playlists workspace tab.
2. Click New Smart Playlist (the wand icon).
3. Name it and press Enter.
4. The editor opens in Rules view by default.

Smart playlists appear in the same list as regular playlists, with a wand icon to distinguish them.

Rule Builder

Each smart playlist is defined by one or more condition groups. Each group contains conditions linked by AND or OR logic. Groups themselves are also evaluated together.

Condition Mode: Hard vs Soft

Each individual condition has a mode:

Mode	Effect
Hard	Acts as a filter — if the condition fails, the track is excluded entirely
Soft	Acts as a scorer — the track is not excluded, but matched tracks rise higher in the sorted results

Soft conditions have a configurable weight (default 1.0). Higher weight means more influence on the score rank.

Tip

Use Hard conditions to define what you want, and Soft conditions to prefer the best matches. For example, Hard-require Genre contains "Jazz" and Soft-prefer Energy > 0.7 to get jazz tracks ranked by energy.

Rule Fields

Field	Type	Notes
Title	Text
Artist	Text
Album	Text
Genres	Tag list	A track can have multiple genres
Year	Number
Duration (seconds)	Number
Days since added	Number (virtual)	Calculated from import date
BPM	Number
Musical Key	Text	Camelot notation (e.g. 8B) or standard
Energy	Number 0–1	Spectral energy level
Mood Tags	Tag list	e.g. upbeat, melancholy, tense
Explicit	Boolean	true / false
Custom Tags	Tag list	User-defined tags applied in the library
Category	Text (virtual)	Matches by file path prefix

Operators

Operator	Applies to
contains	Text, tag list fields
not contains	Text, tag list fields
is	Text, number, key, boolean fields
is not	Text, number, key, boolean fields
is one of	Text, tag list — comma-separated values
is not one of	Text, tag list — comma-separated values
greater than	Number fields
less than	Number fields
between	Number fields (min and max)

Example Rules

Jazz tracks added in the last 30 days:

[Hard] Genres contains "Jazz"
[Hard] Days since added less than 30

Uptempo tracks for a drive show, preferring high energy:

[Hard] BPM greater than 120
[Hard] Duration between 180 and 360
[Soft] Energy greater than 0.7   (weight 2.0)

Any Miles Davis or John Coltrane:

[Hard] Artist is one of "Miles Davis, John Coltrane"

Explicit-free tracks from a set of genres:

[Hard] Genres is one of "Pop, R&B, Hip-Hop"
[Hard] Explicit is false

Sort Options

After conditions are evaluated, brūhi sorts the resulting tracks:

Sort	Description
Random	Shuffled on each evaluation
Score	Soft-condition score descending — best matches first
Alphabetical	By track title, A–Z
By Artist	A–Z by artist name
By BPM	Ascending or descending BPM
By Energy	Ascending or descending energy level
By year	Oldest or newest first
By date added	Most recently imported first
By duration	Shortest or longest first

Tip

Score sort is most useful when you have multiple Soft conditions. Each matched Soft condition adds its weight to the track’s score, so the most-suitable tracks naturally float to the top.

Limits

Limit	Description
Max tracks	Stop after N tracks
Max duration	Stop when total playtime reaches N minutes

Both limits are applied after sorting.

Playback Behaviour

The Playback Behaviour panel controls how smart playlists are used at runtime (scheduling and automation):

Repeat Windows

Prevent the same track or artist from appearing too soon after a previous play.

Setting	Description
Track repeat window	Suppress a track for N minutes after it was last played
Artist repeat window	Suppress all tracks by the same artist for N minutes

Repeat windows use an in-memory play history. The history persists for the life of the process (Desktop session or Cloud server process).

☁️ Cloud

On brūhi Cloud the play history is reset if the server process restarts (e.g. container redeploy). For persistent scheduling history across restarts, use the Schedule module.

Harmonic Scheduling

When Prefer harmonic is enabled, brūhi uses the Camelot Wheel to select the next track. From the filtered pool it picks a track whose musical key is compatible with the last-played key.

Compatible key relationships on the Camelot Wheel:

• Same key (same number + same mode letter)
• Adjacent on the wheel (±1 in number, same mode letter)
• Relative major/minor (same number, A ↔ B)

For example, if the last track played was in 8B (C major), harmonically compatible keys are 7B, 9B, and 8A.

If no harmonically compatible track exists in the pool, a random track is selected as a fallback.

Preview Matches

Click Preview Matches to see which tracks from your library would be included right now, without loading the playlist to a deck. Use this to validate your rules before scheduling.

Script Mode

🖥️ Desktop only

In addition to the visual rule builder, Desktop smart playlists can be defined using brūhi Script — a simple sandbox scripting language.

Click the Script toggle to switch from the Rules view to the Script editor. Your rules are not converted automatically; Script mode and Rules mode are independent.

Example script for a 20-track jazz shuffle:

tracks = library.search("genre:Jazz").shuffle().limit(20)
playlist.set(tracks)

See brūhi Script for the full language reference.

Updating the Playlist

Smart playlists are evaluated when:

1. You click Preview Matches or load the playlist to a deck.
2. The scheduler or automation rule triggers the playlist.
3. On brūhi startup (Desktop), playlists are re-evaluated against the current library state.

Changes to your library (new imports, deletions) are reflected the next time the smart playlist is evaluated.

Persistence

Smart playlist rules are stored in the SQLite database alongside regular playlists. Both types appear together in the playlist list with different icons.