Searching

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 tuple.

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"

Copyright 2014 Banshee contributors. Banshee is a registered trademark of Novell.