Banshee supports a very extensive user search language, which is actually a super-set of the Xesam user search language. The search language is very similar to that which is supported by Google and other major search engines and desktop search applications, such as Beagle.
Basic Terms
At the most basic, a query consists simply of some search terms. This can be as simple as dave matthews, in which case all default fields are searched (Track Title, Artist, Album Title, etc.), and any track whose fields contain both dave and matthews is returned. Queries are also always case insensitive. That is, dave, Dave, and DAVE all mean the same thing.
Examples
| Query | Description |
|---|---|
dave matthews |
Matches any track fields that contain both dave and matthews |
"dave matthews |
Matches any track fields that contains literally dave matthews |
"dave matthews" |
Same as above, but with a closing quote, which is only necessary if more search terms will be provided |
It is important to note that white space is significant in a search if it is not enclosed in quotes. The search dave matthews actually contains two separate terms, dave and matthews. To search for the literal string “dave matthews”, a double quote must precede the search term, and optionally follow it if more terms are to be provided. Two terms with no explicit operator between them imply an AND operation.
Basic Operators
Operators can be placed between two terms or can proceed a single term. The default operation is AND, and is implied when there is no explicit operator between two terms. Because it is the default, there is no explicit AND operator.
Other basic operations include OR and NOT. Together, these three operations can yield very powerful queries.
List of logical operators
| Operator | Description |
|---|---|
| default, white space | Boolean AND two terms with white space between them |
OR, or, |, , |
Boolean OR two terms |
NOT, not, - |
Negate the term following the operator |
Examples of logical operations
| Query | Description |
|---|---|
dave matthews |
Matches any fields in a track containing both dave and matthews |
dave, matthews |
Matches any fields in a track containing either dave or matthews |
dave or matthews |
Same as above |
dave | matthews |
Same as above |
-"dave matthews" |
Matches all tracks whose fields do not contain dave matthews |
Fields
To perform more powerful queries and to limit the scope of comparisons, fields can be specified. Fields limit search operations and must be followed by a relation.
In addition to logical operations, relations can be created between terms. Relations include comparisons such as “contains” (the default relation), “starts with”, “equal to”, “less than”, “greater than”, etc. Each of these relations is specified using a relation operator between a field and a term. White space cannot be present at all in the _
A relation is only useful when applied to a field.
List of fields
The following is a list of fields and any aliases that are supported for searching within track metadata. Descriptions are not given for fields that are thought to be obvious. All fields apply to individual tracks (not artist, album) unless otherwise specified.
| Field | Description |
|---|---|
artist, by, artists |
Limit search to the artist's name |
title, titled |
Limit search to the track's title |
album, on, from |
Limit search to the album's title |
disc, discnum, cd |
Limit search to disc number |
year, released |
|
rating, stars |
|
plays, playcount |
Match the play count of a track |
skips, skipcount |
Match how many times a track has been skipped |
path, uri, file |
Match a track's file system path or URI |
mimetype, type, format |
Match a track's file Mime Type |
lastplayed, played |
Match a track's last played date/time; supports the Date Time modifier |
addedon, importedon, dateadded |
Match a track's imported date; supports the Date Time modifier |
size, filesize |
Match a track's file size; supports the File Size modifier |
composer, comment, bpm, score, bitrate, and duration are also available fields
List of relation operators
| Operator | Description |
|---|---|
: |
Field contains a term |
= |
Field starts with a term |
== |
Field is equal to a term |
< |
Field is less than a term (for numerical fields only) |
> |
Field is greater than a term (for numerical fields only) |
<= |
Field is less than or equal to a term (for numerical fields only) |
>= |
Field is greater than or equal to a term (for numerical fields only) |
Examples of fields and relations
| Query | Description |
|---|---|
title:fraud |
Match tracks where the track title contains "fraud" |
on=awkward |
Match tracks where the album title starts with "awkward" |
by=="august burns red" |
Match tracks where the artist is exactly "august burns red" |
rating>3 |
Match tracks where the rating is greater than 3 |
Modifiers
Some fields support terms that can be formatted specially. These fields transform specially formatted input into the proper format for matching/searching so queries can be more user friendly. These transformations are handled by modifiers.
For example, the filesize field uses the FileSize modifier to accept input such as 45MB or 5G, instead of requiring 47185920 and 5368709120 respectively (internally, filesize comparisons are made in bytes).
List of Modifiers
Check the list of fields to see which fields support which modifiers.
| Modifier | Description |
|---|---|
| FileSize | Takes an integer with an optional multiplier, which must be one of K, M, G, or T and can optionally end in B. The multipliers are case insensitive. The input is translated into bytes. |
| DateTime | Takes a valid date/time string and computes a UNIX time-stamp. |
Examples of Modifiers
| Query | Description |
|---|---|
filesize<5m |
Match any tracks whose file size is under 5 megabytes |
filesize>=10GB |
Match any tracks whose file size is greater than or equal to 10 gigabytes |
addedon>"2007-12-01" |
Match any tracks added to the library after December 1, 2007 |
Grouping
Finally, queries can contain grouping to enforce order of operations. This is accomplished by using parenthesis, as one might expect. In most situations, this level of granularity in a user search query is not necessary, though it is nevertheless supported.
Examples of grouping
| Query | Description |
|---|---|
by:"dave matthews", (by=august on=messengers) |
Matches any tracks whose title contains "dave matthews", or, any tracks whose artist starts with "august" and whose album title starts with "messengers" |
(by:"dave matthews", (by=august on=messengers)) rating>2 |
Same as the above, except further restricts the search to match tracks whose rating is also greater than 2 |
(by:"dave matthews", (by=august on=messengers)) | rating>2 |
Same as the first example, except it also matches any other tracks whose rating is greater than 2 |
-mimetype:wma by=gogol |
Show all non-WMA tracks by artists starting with "Gogol" |