Class: RoonApiBrowse

RoonApiBrowse(core)

new RoonApiBrowse(core)

Roon API Browse service. The browse service allows you to present a hierarchical, list-based user interface for Roon.

Your browsing session is maintained on Roon's side, facilitating minimally stateful clients.

## Sessions

In order to facilitate minimally stateful clients and avoid situations where large amounts of data need to be sent at once, the browse session state is maintained on the server (Roon Core) side.

Requests to the browse service accept two arguments:

  • `hierarchy` which identifies the hierarchy being browsed

  • `multi_session_key`, which enables an extensions to browse multiple instances of the same hierarchy at once. Most applications should not use `multi_session_key`.

Keep in mind when integrating with this API that in most cases, it will be better for the user to remember their last browsing position. In other cases where starting the browse from the toplevel is more appropriate, call the browse method with opts.pop_all set to true

## The Browse Stack

Roon keeps track your browse stack, which consists of one or more _levels_.

Levels are numbered starting from 0 (the top level). The level number increases as the user "drills down".

Parameters:
Name Type Description
core Core The Core providing the service
Source:

Methods

browse(opts, cbopt)

Perform a browsing operation. Use this when the user selects an `Item`
Parameters:
Name Type Attributes Description
opts object Options. If none, specify empty object ({}).
Properties
Name Type Attributes Description
hierarchy string The hierarchy is being browsed. 
           The following values are currently supported:

            * "browse" -- If you are exposing a general-purpose browser, this is what you should use
            * "playlists" 
            * "settings" 
            * "internet_radio"
            * "albums"
            * "artists"
            * "genres"
            * "composers"
            * "search"
multi_session_key string <optional>
 If your application browses several instances of the same hierarchy at the same time, you can populate this to distinguish between them. Most applications will omit this field.
item_key string <optional>
 The key from an `Item` If you omit this, the most recent level will be re-loaded.
input string <optional>
 Input from the input box
zone_or_output_id string <optional>
 Zone ID. This is required for any playback-related functionality to work.
pop_all bool <optional>
 True to pop all levels but the first
pop_levels int <optional>
 If set, pop n levels
refresh_list bool <optional>
 If set, refresh the list contents
set_display_offset int <optional>
 Update the display offset for the current list prior to performing the browse operation 
           If true, then the session will be reset so that browsing begins from the root of the hierarchy. 
           If this is false or unset, then the core will attempt to resume at the previous browsing position
           It is not valid to provide `pop_all` and `item_key` at the same time
cb RoonApiBrowse~browseresultcallback <optional>
 Called on success or error
Source:

load(opts, cbopt)

Retrieve items from a browse level. Item loading is handled separately from browsing. This allows clients to load very large lists in very small increments if needed.
Parameters:
Name Type Attributes Description
opts object Options.
Properties
Name Type Attributes Description
set_display_offset int <optional>
 Update the display offset for the current list
level int <optional>
 Which level of the browse hierarchy to load from. Defaults to the current (deepest) level.
offset int <optional>
 Offset into the list where loading should begin. Defaults to 0.
count int <optional>
 Number of items to load. Defaults to 100.
hierarchy string The hierarchy is being browsed. See `browse` for a list of possible values
multi_session_key string <optional>
 If your application browses several instances of the same hierarchy at the same time, you can populate this to distinguish between them. Most applications will omit this field.
cb RoonApiBrowse~loadresultcallback <optional>
 Called on success or error
Source:

Type Definitions

browseresultcallback(error, body)

Parameters:
Name Type Description
error string | false an error code or false if no error
body object
Properties
Name Type Attributes Description
action string The action that the client should take as a result of this load 
               Possible values include:

                * "message"                - Display an message to the user, see the `message` and `is_error` properties
                * "none"                   - No action is required
                * "list"                   - The current list or its contents have changed. See the `list` property for the new level, and load items using the `load` request
                * "replace_item"           - Replace the selected item with the item in the `item` property
                * "remove_item"            - Remove the selected item
item Item <optional>
 When the action is "replace_item", this is the replacement item
list List <optional>
 When the action is "list", this represents the current list
message string <optional>
 When the action is 'message', this is the message to display
is_error bool <optional>
 When the action is 'message', this indicates whether the message represents an error or not
Source:

loadresultcallback(error, body)

Parameters:
Name Type Description
error string | false an error code or false if no error
body object
Properties
Name Type Description
items Array.<Item>
offset number
list List
Source: