paracusia

v0.2.11

paracusia v0.2.11 Paracusia.MpdClient.Database

Functions related to the music database.

See also: https://musicpd.org/doc/protocol/database.html

Link to this section Summary

Functions

count(filters)

Returns the total playtime and number of songs that match the given filters

count_grouped(group, filters \\ [])

Same as count/1, but results are grouped with the additional parameter group

filter(filters)
find(filters)

Returns all songs that match the given filters

find_add(filters)

Adds all songs that match the given filters to the queue

get(fe)

Returns all songs that match the given filter expression

list(tag, filters \\ [])

Returns unique tag values that match the given query

list_all(uri)

Lists all songs and directories in uri

list_all_info(uri \\ "")

Same as list_all/1, except it also returns metadata info

list_files(uri \\ "")

Returns the contents of the directory uri, including files are not recognized by MPD

lsinfo(uri \\ "")

Returns the contents of the directory uri

order_by(fe, tag)

Returns the given FindExpression with the order_by restriction added. See get/1 for an example

order_by(fe, tag, sort_direction)

Returns the given FindExpression with the order_by restriction added. Results will be sorted by tag in ascending order. See get/1 for an example

read_comments(uri)

Returns "comments" (i.e., key-value pairs) from the file specified by uri

rescan()

Same as update/0, but also rescans unmodified files

rescan(uri)

Same as update/1, but also rescans unmodified files

search(filters)

Case-insensitive version of find/1

search_add(filters)

Case-insensitive version of find_add/1

search_add_playlist(playlist, filters)

Performs a case-insensitive search with the given filters and adds matching songs to the given playlist

update()

Updates the entire music database and returns the job id

update(uri)

Same as update/0, but only the given URI (directory or file) is updated

window(fe, from, until)

Link to this section Functions

Link to this function

count(filters) 
count([{Paracusia.MpdTypes.tag(), String.t()}]) ::
  {:ok, map()} | Paracusia.MpdTypes.mpd_error()

Returns the total playtime and number of songs that match the given filters.

Example 

Paracusia.MpdClient.Database.count(albumartist: "Rammstein", album: "Mutter")
{:ok, %{"playtime" => 3048, "songs" => 11}}
Link to this function

count_grouped(group, filters \\ []) 
count_grouped(Paracusia.MpdTypes.tag(), [{Paracusia.MpdTypes.tag(), String.t()}]) ::
  {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Same as count/1, but results are grouped with the additional parameter group.

Example 

# Show the number of songs and total playlength of each album by "Rammstein":
Paracusia.MpdClient.Database.count_grouped(:album, albumartist: "Rammstein")
{:ok,
  [%{"Album" => "Mutter", "playtime" => 3048, "songs" => 11},
   %{"Album" => "Reise, Reise", "playtime" => 3385, "songs" => 14}]}
Link to this function

filter(filters) 
filter([{Paracusia.MpdTypes.find_tag(), String.t()}]) ::
  Paracusia.MpdClient.Database.FindExpression.t()

Link to this function

find(filters) 
find([{Paracusia.MpdTypes.find_tag(), String.t()}]) ::
  {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Returns all songs that match the given filters.

Example 

# Return all songs by "Rammstein" in the album "Mutter":
Paracusia.MpdClient.Database.find(albumartist: "Rammstein", album: "Mutter")
{:ok,
  [%{"Album" => "Mutter", "AlbumArtist" => "Rammstein",
      "Date" => "2001", "Time" => "280", "Title" => "Mein Herz brennt",
      "file" => "flac/rammstein_-_mutter/rammstein_mein_herz_brennt.flac", …},
    %{"Album" => "Mutter", "AlbumArtist" => "Rammstein",
      "Date" => "2001", "Time" => "217", "Title" => "Links 2-3-4",
      "file" => "flac/rammstein_-_mutter_(2001)/02._rammstein_links_2_3_4.flac", …},
    …
    ]
}
Link to this function

find_add(filters) 
find_add([{Paracusia.MpdTypes.find_tag(), String.t()}]) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Adds all songs that match the given filters to the queue.

Example 

# Add album "Mutter" by "Rammstein":
Paracusia.MpdClient.Database.find_add(albumartist: "Rammstein", album: "Mutter")
:ok
Link to this function

get(fe)

Returns all songs that match the given filter expression.

Example 

# Return the first three songs by "Koan" in the album "Proteus", in descending order sorted by
# their title:
  Paracusia.MpdClient.Database.filter(albumartist: "Koan", album: "Proteus")
  |> Paracusia.MpdClient.Database.order_by("Title", :desc)
  |> Paracusia.MpdClient.Database.window(0, 3)
  |> Paracusia.MpdClient.Database.get
  {:ok,
    [
      %{
        "Album" => "Proteus",
        "AlbumArtist" => "Koan",
        "AlbumArtistSort" => "Koan",
        "Title" => "Splice (White mix)",
        …
      },
      %{
        "Album" => "Proteus",
        "AlbumArtist" => "Koan",
        "AlbumArtistSort" => "Koan",
        "Artist" => "Koan",
        "Title" => "Eidotheia (radio version)",
        …
      },
      %{
        "Album" => "Proteus",
        "AlbumArtist" => "Koan",
        "AlbumArtistSort" => "Koan",
        "Title" => "Arachne (Fatum Sci-Fi version)",
        }
    ]
  }
Link to this function

list(tag, filters \\ []) 
list(Paracusia.MpdTypes.tag() | :file, [{Paracusia.MpdTypes.tag(), String.t()}]) ::
  {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Returns unique tag values that match the given query.

tag specifies which tag values should be returned. filter allows to specify a list of tag-value pairs to filter the results.

Example 

# Return all albums released by Rammstein in 2001:
Paracusia.MpdClient.Database.list(:album, albumartist: "Rammstein", date: 2001)
{:ok, ["Mutter"]}
Link to this function

list_all(uri) 
list_all(String.t()) ::
  {:ok, [{String.t(), String.t()}]} | Paracusia.MpdTypes.mpd_error()

Lists all songs and directories in uri.

Usage of this command is discouraged by the author of MPD.

Link to this function

list_all_info(uri \\ "") 
list_all_info(String.t()) :: {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Same as list_all/1, except it also returns metadata info.

Usage of this command is discouraged by the author of MPD.

Link to this function

list_files(uri \\ "") 
list_files(String.t()) :: {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Returns the contents of the directory uri, including files are not recognized by MPD.

uri can be a path relative to the music directory or an URI understood by one of the storage plugins.

Link to this function

lsinfo(uri \\ "") 
lsinfo(String.t()) :: {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Returns the contents of the directory uri.

When listing the root directory, this currently returns the list of stored playlists. This behavior is deprecated; use Paracusia.MpdClient.Playlists.list_all/0 instead. This command may be used to list metadata of remote files (e.g. uri beginning with "http://" or "smb://"). Clients that are connected via UNIX domain socket may use this command to read the tags of an arbitrary local file (the URI is an absolute path).

Link to this function

order_by(fe, tag) 
order_by(
  Paracusia.MpdClient.Database.FindExpression.t(),
  Paracusia.MpdTypes.tag()
) :: Paracusia.MpdClient.Database.FindExpression.t()

Returns the given FindExpression with the order_by restriction added. See get/1 for an example.

Link to this function

order_by(fe, tag, sort_direction) 
order_by(
  Paracusia.MpdClient.Database.FindExpression.t(),
  Paracusia.MpdTypes.tag(),
  Paracusia.MpdTypes.sort_direction()
) :: Paracusia.MpdClient.Database.FindExpression.t()

Returns the given FindExpression with the order_by restriction added. Results will be sorted by tag in ascending order. See get/1 for an example.

Link to this function

read_comments(uri) 
read_comments(String.t()) :: {:ok, map()} | Paracusia.MpdTypes.mpd_error()

Returns "comments" (i.e., key-value pairs) from the file specified by uri.

uri can be a path relative to the music directory or an absolute path. May also be used to list metadata of remote files (e.g. URI beginning with "http://" or "smb://"). The meaning of the returned key-value pairs depends on the codec, and not all decoder plugins support it.

Link to this function

rescan() 
rescan() :: {:ok, pos_integer()} | Paracusia.MpdTypes.mpd_error()

Same as update/0, but also rescans unmodified files.

Link to this function

rescan(uri) 
rescan(String.t()) :: {:ok, pos_integer()} | Paracusia.MpdTypes.mpd_error()

Same as update/1, but also rescans unmodified files.

Link to this function

search(filters) 
search([{Paracusia.MpdTypes.find_tag(), String.t()}]) ::
  {:ok, [map()]} | Paracusia.MpdTypes.mpd_error()

Case-insensitive version of find/1.

Link to this function

search_add(filters) 
search_add([{Paracusia.MpdTypes.find_tag(), String.t()}]) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Case-insensitive version of find_add/1.

Link to this function

search_add_playlist(playlist, filters) 
search_add_playlist(String.t(), [{Paracusia.MpdTypes.find_tag(), String.t()}]) ::
  :ok | Paracusia.MpdTypes.mpd_error()

Performs a case-insensitive search with the given filters and adds matching songs to the given playlist.

Example 

Paracusia.MpdClient.Database.search_add_playlist("Mutter by Rammstein", albumartist: "Rammstein", album: "Mutter")
:ok
Link to this function

update() 
update() :: {:ok, pos_integer()} | Paracusia.MpdTypes.mpd_error()

Updates the entire music database and returns the job id.

Find new files, remove deleted files and update modified files. The returned id is used to identify the update job. The current job id can be read from Paracusia.MpdClient.Status.status/0 (updating_db).

Link to this function

update(uri) 
update(String.t()) :: {:ok, pos_integer()} | Paracusia.MpdTypes.mpd_error()

Same as update/0, but only the given URI (directory or file) is updated.

Link to this function

window(fe, from, until)