The `Client` Class¶

class pyfoobeef.client.Client(base_url: str, port: int, username: Optional[str] = None, password: Optional[str] = None, timeout: float = 10.0)¶

Synchronous class for interacting with the beefweb plugin.

Parameters:	base_url – The base URL for beefweb’s server. i.e. “localhost” port – The port number of beefweb’s server. username – The username to use if authentification is enabled in beefweb. password – The password to use if authentification is enabled in beefweb. timeout – The maximum amount of time to wait when making a http request.

add_playlist(title: str, index: Optional[int] = None, return_playlist: Optional[bool] = True) → Optional[pyfoobeef.models.PlaylistInfo]¶

Create a new playlist.

Parameters:	title (str) – The title of the playlist. index (Optional[int]) – The numerical index to insert the new playlist. None = last position. return_playlist (Optional[bool]) – If True automatically makes a second request to beefweb to retrieve the playlist info for the new playlist. There is a small chance that the incorrect playlist will be returned during the second request (i.e. if a playlist is added or removed between api calls). In this case an AssertionError will be raised.
Returns:	A PlaylistInfo namedtuple if return_playlist is True else None
Return type:	Optional[PlaylistInfo]

add_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], items: Union[List[Union[str, FileSystemEntry]], Tuple[List[Union[str, FileSystemEntry]]]], dest_index: Optional[int] = None, asynchronous: bool = False) → None¶

Add items to a playlist.

Parameters:

playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index.
items (Paths) – A list or tuple of strings or FileSystemEntry objects containing the paths of files and/or directories to add. Note that the paths including the drive letter are case sensitive even in Windows.
dest_index (Optional[int]) – The index in the playlist to insert the new items.
asynchronous (bool) – Set to True to not wait for the media player to finish processing the added items before returning. Default = False.

Warning

The paths including the drive letter are case sensitive even in windows.

clear_playlist(playlist_ref: Union[str, int, PlaylistInfo]) → None¶

Remove all items from a playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index.

copy_between_playlists(source_playlist: Union[str, int, PlaylistInfo], dest_playlist: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]], dest_index: Optional[int] = None) → None¶

Copy items to a different playlist.

Parameters:

source_playlist (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index of the source.
dest_playlist (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index of the destination.
item_indices (ItemIndices) – List or tuple of the indices of the items to be copied.
dest_index (Optional[int]) – The index in the playlist to insert the copies. None = copy to the end of the playlist.

copy_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]], dest_index: Optional[int] = None) → None¶

Copy items to the same playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. item_indices (ItemIndices) – List or tuple of the indices of the items to be copied. dest_index (Optional[int]) – The index in the playlist to insert the copies. None = copy to the end of the playlist.

find_playlist(title: Optional[str] = None, search_id: Optional[str] = None) → Optional[pyfoobeef.models.PlaylistInfo]¶

Get an object representing a specific playlist.

Parameters:	title (Optional[str]) – String representing the playlist’s title. search_id (Optional[str]) – The id of the playlist.
Returns:	A PlaylistInfo namedtuple or None if not found.
Return type:	Optional[PlaylistInfo]

get_artwork(playlist_ref: Union[str, int, PlaylistInfo], index: int) → None¶

Get an items artwork.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. index (int) – The index of the item to get artwork for.

get_browser_entries(path: str) → pyfoobeef.models.BrowserEntry¶

Get files and directories from a specific path.

Parameters:	path (str) – The path to the directory or file to retrieve. Note that even in windows the path including the drive letter is case sensitive (r”C:\Music” will work, r”c:\Music” will not).

Warning

Even in windows the path including the drive letter is case sensitive (r”C:\Music” will work, r”c:\Music” will not).

Returns:	A BrowserEntry object.
Return type:	BrowserEntry

get_browser_roots() → pyfoobeef.models.BrowserEntry¶

Get all the files and directories accessable by beefweb.

Returns:	A BrowserEntry object.
Return type:	BrowserEntry

get_player_state(column_map: Union[Dict[str, str], Set[str], List[str], Tuple[str], None] = None) → pyfoobeef.models.PlayerState¶

Get the status of the player.

Parameters:

column_map (Optional[ColumnsMap]) –

Dict, list, tuple, or set where each key (for dict, set) or item (for list, tuple) is the active item field to request. If a dict is used each value is the attribute name to map that key to the returned Column object.

If this argument is not specified a default column map will be used.

Note

Names that would be invalid as Python attrubute names may only be accessed through subscripting (i.e. “%title%” or “my custom name”).

Examples- {“%track artist%”: “artist”} will result in the returned object having an active_item.columns.artist attribute containing information returned from the active item’s %track artist% field.

[“%title%”, “%album%”] will result in the returned object bieng subscriptable like active_item.columns[“%album%”] which will return information returned from the active item’s %album% field.

Returns: PlayerState object

Return type: PlayerState

get_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], offset: int = 0, count: int = 1000000, column_map: Union[Dict[str, str], Set[str], List[str], Tuple[str], None] = None) → pyfoobeef.models.PlaylistItems¶

Get an object representing the items in a specific playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. offset (int) – The start index of the items to retrieve. count (int) – The amount of items to retrieve. column_map (Optional[ColumnsMap]) – Dict, list, tuple, or set where each key (for dict, set) or item (for list, tuple) is the item field to request. If a dict is used each value is the attribute name to map that key to the returned Column object. If this argument is not specified a default column map will be used. Note Names that would be invalid as Python attrubute names may only be accessed through subscripting (i.e. “%title%” or “my custom name”). Examples- {“%track artist%”: “artist”} will result in the returned object having an active_item.columns.artist attribute containing information returned from the active item’s %track artist% field. [“%title%”, “%album%”] will result in the returned object bieng subscriptable like active_item.columns[“%album%”] which will return information returned from the active item’s %album% field.
Returns:	A PlaylistItems object.
Return type:	PlaylistItems

get_playlists() → pyfoobeef.models.Playlists¶

Get an object representing the playlists.

Returns:	A Playlists object
Return type:	Playlists

move_between_playlists(source_playlist: Union[str, int, PlaylistInfo], dest_playlist: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]], dest_index: Optional[int] = None) → None¶

Move items to a different playlist.

Parameters:

source_playlist (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index of the source.
dest_playlist (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index of the destination.
item_indices (ItemIndices) – List or tuple of the indices of the items to be moved.
dest_index (Optional[int]) – The index in the playlist to insert the copies. None = copy to the end of the playlist.

move_playlist(playlist_ref: Union[str, int, PlaylistInfo], new_index: int) → None¶

Move a playlist to a new index.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. index (int) – The new index of the playlist. Negative value to make it the last playlist.

move_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]], dest_index: Optional[int] = None) → None¶

Move items to a different index in the same playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. item_indices (ItemIndices) – List or tuple of the indices of the items to be moved. dest_index (Optional[int]) – The index in the playlist to insert the copies. None = copy to the end of the playlist.

pause() → None¶: Pause playback.

pause_toggle() → None¶: Toggle pause state.

play() → None¶: Start playback.

Note

Note that the item played will be from the last playlist that an item was played from even if another playlist is set as current. Use the play_specific method first to play an item from a specific playlist.

play_next(by: str = None) → None¶

Play the next item in the last played playlist.

Note

Note that the item played will be from the last playlist that an item was played from even if another playlist is set as current. Use the play_specific method first to play an item from a specific playlist.

Parameters:	by (str) – The media player field used to determine what counts as next (i.e. “%title%”). None = use the items index in the playlist.

play_previous(by: str = None) → None¶

Play the previous item in the last played playlist.

Note

Note that the item played will be from the last playlist that an item was played from even if another playlist is set as current. Use the play_specific method first to play an item from a specific playlist.

Parameters:	by (str) – The media player field used to determine what counts as previous (i.e. “%title%”). None = use the items index in the playlist.

play_random() → None¶: Play a random item from the last played playlist.

Note

Note that the item played will be from the last playlist that an item was played from even if another playlist is set as current. Use the play_specific method first to play an item from a specific playlist.

play_specific(playlist_ref: Union[str, int, PlaylistInfo], index: int) → None¶

Start playback of a specific item from a specific playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical index of the playlist that contains the media to play. index (int) – The index number of the item to play.

remove_playlist(playlist_ref: Union[str, int, PlaylistInfo]) → None¶

Remove a playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index.

remove_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]]) → None¶

Remove items from a playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. item_indices (ItemIndices) – List or tuple of the indices of the items to be removed.

set_current_playlist(playlist_ref: Union[str, int, PlaylistInfo]) → None¶

Set the currently selected playlist.

Parameters:	playlist_ref – The PlaylistInfo object, ID, or numerical playlist index.

set_player_state(volume: Optional[float] = None, mute: Optional[bool] = None, position: Optional[float] = None, relative_position: Optional[float] = None, playback_mode: Optional[int] = None) → None¶

Set the volume level, playback position, and playback order.

Note

Note that the value for the volume parameter may need to be a negative number to work correctly. Use information returned by get_player_state to determine the min and max values for the connected media player.

Parameters:

volume (Optional[float]) – Floating point number to set the player’s volume level. Value may need to be a negative number to work correctly. Use information returned by get_player_state to determine the min and max values for the connected media player.
mute (Optional[bool]) – True = muted, False = unmuted, None = no change.
position (Optional[float]) – Sets the position of the current track in seconds.
relative_position (Optional[float]) – Seconds to Add or subtract from the current position.
playback_mode (Optional[int]) – Numerical mode that sets playback order (repeat, random, shuffle, etc.). Use the playback_modes attribute from get_player_state() to determine the possible choices.

set_playlist_title(playlist_ref: Union[str, int, PlaylistInfo], title: str) → None¶

Change a playlist’s title.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. title (str) – The new title of the playlist.

sort_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], by: str, desc: bool = False, random: bool = False) → None¶

Sort the items in a playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. by (str) – The media player field to sort by (i.e. “%title%”). desc (bool) – Sort in descending order. random (bool) – Sort in random order.

stop() → None¶: Stop playback.

The `AsyncClient` Class¶

class pyfoobeef.async_client.AsyncClient(base_url: str, port: int, username: Optional[str] = None, password: Optional[str] = None, timeout: float = 10.0)¶

Asynchronous class for interacting with the beefweb plugin.

Parameters:	base_url – The base URL for beefweb’s server. i.e. “localhost” port – The port number of beefweb’s server. username – The username to use if authentification is enabled in beefweb. password – The password to use if authentification is enabled in beefweb. timeout – The maximum amount of time to wait when making a http request.

add_playlist(title: str, index: Optional[int] = None, return_playlist: Optional[bool] = True) → Optional[pyfoobeef.models.PlaylistInfo]¶

Create a new playlist.

Parameters:	title (str) – The title of the playlist. index (Optional[int]) – The numerical index to insert the new playlist. None = last position. return_playlist (Optional[bool]) – If True automatically makes a second request to beefweb to retrieve the playlist info for the new playlist. There is a small chance that the incorrect playlist will be returned during the second request (i.e. if a playlist is added or removed between api calls). In this case an AssertionError will be raised.
Returns:	A PlaylistInfo namedtuple if return_playlist is True else None
Return type:	Optional[PlaylistInfo]

add_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], items: Union[List[Union[str, FileSystemEntry]], Tuple[List[Union[str, FileSystemEntry]]]], dest_index: Optional[int] = None, asynchronous: bool = False) → None¶

Add items to a playlist.

Parameters:

playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index.
items (Paths) – A list or tuple of strings or FileSystemEntry objects containing the paths of files and/or directories to add. Note that the paths including the drive letter are case sensitive even in Windows.
dest_index (Optional[int]) – The index in the playlist to insert the new items.
asynchronous (bool) – Set to True to not wait for the media player to finish processing the added items before returning. Default = False.

Warning

The paths including the drive letter are case sensitive even in windows.

clear_playlist(playlist_ref: Union[str, int, PlaylistInfo]) → None¶

Remove all items from a playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index.

copy_between_playlists(source_playlist: Union[str, int, PlaylistInfo], dest_playlist: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]], dest_index: Optional[int] = None) → None¶

Copy items to a different playlist.

Parameters:

source_playlist (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index of the source.
dest_playlist (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index of the destination.
item_indices (ItemIndices) – List or tuple of the indices of the items to be copied.
dest_index (Optional[int]) – The index in the playlist to insert the copies. None = copy to the end of the playlist.

copy_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]], dest_index: Optional[int] = None) → None¶

Copy items to the same playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. item_indices (ItemIndices) – List or tuple of the indices of the items to be copied. dest_index (Optional[int]) – The index in the playlist to insert the copies. None = copy to the end of the playlist.

find_playlist(title: Optional[str] = None, search_id: Optional[str] = None) → Optional[pyfoobeef.models.PlaylistInfo]¶

Get an object representing a specific playlist.

Parameters:	title (Optional[str]) – String representing the playlist’s title. search_id (Optional[str]) – The id of the playlist.
Returns:	A PlaylistInfo namedtuple or None if not found.
Return type:	Optional[PlaylistInfo]

get_artwork(playlist_ref: Union[str, int, PlaylistInfo], index: int) → None¶

Get an items artwork.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. index (int) – The index of the item to get artwork for.

get_browser_entries(path: str) → pyfoobeef.models.BrowserEntry¶

Get files and directories from a specific path.

Parameters:	path (str) – The path to the directory or file to retrieve. Note that even in windows the path including the drive letter is case sensitive (r”C:\Music” will work, r”c:\Music” will not).

Warning

Even in windows the path including the drive letter is case sensitive (r”C:\Music” will work, r”c:\Music” will not).

Returns:	A BrowserEntry object.
Return type:	BrowserEntry

get_browser_roots() → pyfoobeef.models.BrowserEntry¶

Get all the files and directories accessable by beefweb.

Returns:	A BrowserEntry object.
Return type:	BrowserEntry

get_player_state(column_map: Union[Dict[str, str], Set[str], List[str], Tuple[str], None] = None) → pyfoobeef.models.PlayerState¶

Get the status of the player.

Parameters:

column_map (Optional[ColumnsMap]) –

Dict, list, tuple, or set where each key (for dict, set) or item (for list, tuple) is the active item field to request. If a dict is used each value is the attribute name to map that key to the returned Column object.

If this argument is not specified a default column map will be used.

Note

Names that would be invalid as Python attrubute names may only be accessed through subscripting (i.e. “%title%” or “my custom name”).

Examples- {“%track artist%”: “artist”} will result in the returned object having an active_item.columns.artist attribute containing information returned from the active item’s %track artist% field.

[“%title%”, “%album%”] will result in the returned object bieng subscriptable like active_item.columns[“%album%”] which will return information returned from the active item’s %album% field.

Returns: PlayerState object

Return type: PlayerState

get_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], offset: int = 0, count: int = 1000000, column_map: Union[Dict[str, str], Set[str], List[str], Tuple[str], None] = None) → pyfoobeef.models.PlaylistItems¶

Get an object representing the items in a specific playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. offset (int) – The start index of the items to retrieve. count (int) – The amount of items to retrieve. column_map (Optional[ColumnsMap]) – Dict, list, tuple, or set where each key (for dict, set) or item (for list, tuple) is the item field to request. If a dict is used each value is the attribute name to map that key to the returned Column object. If this argument is not specified a default column map will be used. Note Names that would be invalid as Python attrubute names may only be accessed through subscripting (i.e. “%title%” or “my custom name”). Examples- {“%track artist%”: “artist”} will result in the returned object having an active_item.columns.artist attribute containing information returned from the active item’s %track artist% field. [“%title%”, “%album%”] will result in the returned object bieng subscriptable like active_item.columns[“%album%”] which will return information returned from the active item’s %album% field.
Returns:	A PlaylistItems object.
Return type:	PlaylistItems

get_playlists() → pyfoobeef.models.Playlists¶

Get an object representing the playlists.

Returns:	A Playlists object
Return type:	Playlists

move_between_playlists(source_playlist: Union[str, int, PlaylistInfo], dest_playlist: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]], dest_index: Optional[int] = None) → None¶

Move items to a different playlist.

Parameters:

source_playlist (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index of the source.
dest_playlist (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index of the destination.
item_indices (ItemIndices) – List or tuple of the indices of the items to be moved.
dest_index (Optional[int]) – The index in the playlist to insert the copies. None = copy to the end of the playlist.

move_playlist(playlist_ref: Union[str, int, PlaylistInfo], new_index: int) → None¶

Move a playlist to a new index.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. index (int) – The new index of the playlist. Negative value to make it the last playlist.

move_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]], dest_index: Optional[int] = None) → None¶

Move items to a different index in the same playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. item_indices (ItemIndices) – List or tuple of the indices of the items to be moved. dest_index (Optional[int]) – The index in the playlist to insert the copies. None = copy to the end of the playlist.

pause() → None¶: Pause playback.

pause_toggle() → None¶: Toggle pause state.

play() → None¶: Start playback.

Note

Note that the item played will be from the last playlist that an item was played from even if another playlist is set as current. Use the play_specific method first to play an item from a specific playlist.

play_next(by: str = None) → None¶

Play the next item in the last played playlist.

Note

Note that the item played will be from the last playlist that an item was played from even if another playlist is set as current. Use the play_specific method first to play an item from a specific playlist.

Parameters:	by (str) – The media player field used to determine what counts as next (i.e. “%title%”). None = use the items index in the playlist.

play_previous(by: str = None) → None¶

Play the previous item in the last played playlist.

Note

Note that the item played will be from the last playlist that an item was played from even if another playlist is set as current. Use the play_specific method first to play an item from a specific playlist.

Parameters:	by (str) – The media player field used to determine what counts as previous (i.e. “%title%”). None = use the items index in the playlist.

play_random() → None¶: Play a random item from the last played playlist.

Note

Note that the item played will be from the last playlist that an item was played from even if another playlist is set as current. Use the play_specific method first to play an item from a specific playlist.

play_specific(playlist_ref: Union[str, int, PlaylistInfo], index: int) → None¶

Start playback of a specific item from a specific playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical index of the playlist that contains the media to play. index (int) – The index number of the item to play.

remove_playlist(playlist_ref: Union[str, int, PlaylistInfo]) → None¶

Remove a playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index.

remove_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], item_indices: Union[List[int], Tuple[int]]) → None¶

Remove items from a playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. item_indices (ItemIndices) – List or tuple of the indices of the items to be removed.

set_current_playlist(playlist_ref: Union[str, int, PlaylistInfo]) → None¶

Set the currently selected playlist.

Parameters:	playlist_ref – The PlaylistInfo object, ID, or numerical playlist index.

set_player_state(volume: Optional[float] = None, mute: Optional[bool] = None, position: Optional[int] = None, relative_position: Optional[int] = None, playback_mode: Optional[int] = None) → None¶

Set the volume level, playback position, and playback order.

Note

Note that the value for the volume parameter may need to be a negative number to work correctly. Use information returned by get_player_state to determine the min and max values for the connected media player.

Parameters:

volume (Optional[float]) – Floating point number to set the player’s volume level. Value may need to be a negative number to work correctly. Use information returned by get_player_state to determine the min and max values for the connected media player.
mute (Optional[bool]) – True = muted, False = unmuted, None = no change.
position (Optional[float]) – Sets the position of the current track in seconds.
relative_position (Optional[float]) – Seconds to Add or subtract from the current position.
playback_mode (Optional[int]) – Numerical mode that sets playback order (repeat, random, shuffle, etc.). Use the playback_modes attribute from get_player_state() to determine the possible choices.

set_playlist_title(playlist_ref: Union[str, int, PlaylistInfo], title: str) → None¶

Change a playlist’s title.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. title (str) – The new title of the playlist.

sort_playlist_items(playlist_ref: Union[str, int, PlaylistInfo], by: str, desc: bool = False, random: bool = False) → None¶

Sort the items in a playlist.

Parameters:	playlist_ref (PlaylistRef) – The PlaylistInfo object, ID, or numerical playlist index. by (str) – The media player field to sort by (i.e. “%title%”). desc (bool) – Sort in descending order. random (bool) – Sort in random order.

stop() → None¶: Stop playback.

The `EventListener` Class¶

class pyfoobeef.event_listener.EventListener(base_url: str, port: int, active_item_column_map: Union[Dict[str, str], Set[str], List[str], Tuple[str], None] = None, no_active_item_ignore_time: Optional[float] = 0.25, playlist_ref: Union[str, int, PlaylistInfo, None] = None, playlist_items_column_map: Union[Dict[str, str], Set[str], List[str], Tuple[str], None] = None, offset: Optional[int] = 0, count: Optional[int] = 1000000, username: Optional[str] = None, password: Optional[str] = None)¶

A listener class for the beefweb server’s eventsource.

Parameters:

base_url (str) – The base URL of the beefweb server (i.e. “localhost”).
port (int) – The port number of the beefweb server.
active_item_column_map (Optional[ColumnsMap]) –
Dict, list, tuple, or set where each key (for dict, set) or item (for list, tuple) is the active item field to request. If a dict is used each value is the attribute name to map that key to the returned Column object.

If this argument is not specified a default column map will be used.

Note

Names that would be invalid as Python attrubute names may only be accessed through subscripting (i.e. “%title%” or “my custom name”).

Examples- {“%track artist%”: “artist”} will result in the returned object having an active_item.columns.artist attribute containing information returned from the active item’s %track artist% field.

[“%title%”, “%album%”] will result in the returned object bieng subscriptable like active_item.columns[“%album%”] which will return information returned from the active item’s %album% field.
no_active_item_ignore_time (Optional[float]) – When switching between playlist items the media player will briefly report that there is no active item before updating with the information of the next item. This argument is the amount of time in seconds that these updates will be ignored. If another update comes in during the ignored period and that update shows an active item then the previous update showing no active item will be completely ignored. Set to 0 to disable.
playlist_ref (PlaylistRef) – The ID or numerical index of the playlist to retrieve items from. None = do not retrieve any items.
playlist_items_column_map (Optional[ColumnsMap]) –
Dict, list, tuple, or set where each key (for dict, set) or item (for list, tuple) is the active item field to request. If a dict is used each value is the attribute name to map that key to the returned Column object.

If this argument is not specified a default column map will be used.

Note

Names that would be invalid as Python attrubute names may only be accessed through subscripting (i.e. “%title%” or “my custom name”).

Examples- {“%track artist%”: “artist”} will result in the returned object having an active_item.columns.artist attribute containing information returned from the active item’s %track artist% field.

[“%title%”, “%album%”] will result in the returned object bieng subscriptable like active_item.columns[“%album%”] which will return information returned from the active item’s %album% field.
offset (Optional[int]) – The index offset to retrieve playlist items from when playlist_ref is not set to None.
count (Optional[int]) – The number of playlist items to retrieve when playlist_ref is not set to None.
username (Optional[str]) – The username to use when using authentication with beefweb.
password (Optional[str]) – The password to use when using authentication with beefweb.

add_callback(info_type: str, callback_func: Callable)¶

Add a callback for when certain types of information are received.

Parameters:

info_type (str) – The type of data that will cause the callback to run. Possible values: “player_state”, “playlist_items”, “playlists”
callback_func (Callable) – A reference to the function to use as a callback. Callbacks will receive the following argument when run depending on the info_type: “player_state” = A PlayerState object, “playlist_items” = A PlaylistItems object, “playlists” = A Playlists object

connect(reconnect_time: Optional[float] = 5)¶

Connect to the beefweb eventsource and begin listening for events.

Parameters:	reconnect_time (Optional[float]) – The number of seconds to wait between reconnection attempts.

disconnect()¶: Disconnect from the beefweb eventsource.

is_connected()¶

Return True if the listener is connected to beefweb.

Returns:	True if the connected to the eventsource, False if disconnected or in the process of connecting.
Return type:	bool

player_state = None¶: A PlayerState object representing the current state of the player including the currently active item. Set to None when the listener is not connected.

playlists = None¶: A Playlists object representing the current playlists. Set to None when the listener is not connected.

remove_all_callbacks()¶: Remove all callbacks.

remove_callback(info_type: str, callback_func: Callable)¶

Remove a callback.

Parameters:	info_type (str) – The type of data to remove the callback from. Possible values: “player_state”, “playlist_items”, “playlists” callback_func (Callable) – A reference to the callback function to remove.

class pyfoobeef.event_listener.InfoHandler(return_type, attach_attr, column_map, callbacks)¶

attach_attr¶: Alias for field number 1

callbacks¶: Alias for field number 3

column_map¶: Alias for field number 2

return_type¶: Alias for field number 0

Data Models¶

class pyfoobeef.models.ActiveItem(playlist_id, playlist_index, index, position, duration, columns)¶

A class with information about the media player’s active item.

columns = None¶: A Columns object containing information about the active item’s informaiton fields.

duration = None¶: The duration of the active item in seconds.

duration_hhmmss() → str¶

Return the duration of the active item as hh:mm:ss.

Returns:	The active item’s duration as hh:mm:ss.
Return type:	str

duration_mmss() → str¶

Return the active item’s duration as mm:ss.

Returns:	The active item’s duration as mm:ss.
Return type:	str

has_columns() → bool¶

Indicate if active item returned column information.

Returns:	True if the active item returned column information.
Return type:	bool

index = None¶: The numerical index of the active item. Will be -1 if no item is active.

playlist_id = None¶: The ID of currently selected playlist.

playlist_index = None¶: The numerical index of the currently selected playlist.

position = None¶: The playback position of the active item in seconds.

position_hhmmss() → str¶

Return the playback position of the active item as hh:mm:ss.

Returns:	The playback position of the active item as hh:mm:ss.
Return type:	str

position_mmss() → str¶

Return the playback position of the active item as mm:ss.

Returns:	The playback position of the active item as mm:ss.
Return type:	str

class pyfoobeef.models.BrowserEntry(data)¶

Represents files or directories accessable by the media player.

Iterable and subscriptable.

path_separator = None¶: The character used to seperate directories in the path.

class pyfoobeef.models.Columns(column_map, returned_columns)¶

Represents information returned about an items data fields.

Can be iterated over, subscripted, or addressed by attributes i.e. (columns.title or columns[‘title’]).

Addressing by attributes only works if the name used is not a reserved keyword.

items() → tuple¶: Generate key, value pairs for the columns similar to dict.items.

class pyfoobeef.models.FileSystemEntry(entry, separator)¶

Represents a file or directory accessable by the media player.

is_directory() → bool¶

Indicate if the item is a directory.

Returns:	True if the item is a directory, False if it is a file.
Return type:	bool

is_file() → bool¶

Indicate if the item is a file.

Returns:	True if the item is a file, False if it is a directory.
Return type:	bool

name = None¶: The file or directory name.

path = None¶: The full path of the file or directory.

separator = None¶: The character used to seperate directories in the path.

size = None¶: The file size in bytes. 0 for directories.

timestamp = None¶: The timestamp of the file or directory.

class pyfoobeef.models.IndexItem(index, item)¶

Represents the index of an item in the media player and its returned data fields.

Parameters:	index (int) – Index of the item in the media player item (Columns) – The returned data fields from the request.

index¶: Alias for field number 0

item¶: Alias for field number 1

class pyfoobeef.models.PlaybackMode(number, mode)¶

Represents the possible playback modes returned from the media player.

Parameters:	number (int) – The numerical index of this mode. mode (str) – The name of this mode.

mode¶: Alias for field number 1

number¶: Alias for field number 0

class pyfoobeef.models.PlayerInfo(name, title, version, plugin_version)¶

Represents information about the media player.

Parameters:	name (str) – The media player name. title (str) – The media player title. version (str) – The media player version number. plugin_version (str) – The beefweb version.

name¶: Alias for field number 0

plugin_version¶: Alias for field number 3

title¶: Alias for field number 1

version¶: Alias for field number 2

class pyfoobeef.models.PlayerState(data, column_map=None)¶

A class representing the state of the player.

active_item = None¶: An ActiveItem object with information about the current active item.

estimated_position() → float¶

Get the estimated playback position since the last update.

Returns:	The estimated playback position in seconds of the active item since this playback object was created. If the estimated position is greater than the active item’s duration will return the active item’s duration. If the playback state is not “playing” will return the active item’s position.
Return type:	float

estimated_position_hhmmss() → str¶

Identical to the estimated_position method but returns hh:mm:ss.

Returns:	Output of the estimated_position method as hh:mm:ss.
Return type:	str

estimated_position_mmss() → str¶

Identical to the estimated_position method but returns mm:ss.

Returns:	Output of the estimated_position method as mm:ss.
Return type:	str

info = None¶: A PlayerInfo namedtuple with information about the media player.

parsed_response = None¶: The original parsed JSON response from beefweb.

playback_mode = None¶: An PlaybackMode namedtuple that indicates the current playback mode.

playback_modes = None¶: A tuple of PlaybackMode namedtuples that indicate the possible playback modes and their number.

playback_state = None¶: A string with information about the playback state (i.e. “paused”).

volume = None¶: A Volume namedtuple with information about the volume level.

class pyfoobeef.models.PlaylistInfo(id, index, title, is_current, item_count, total_time)¶

Represents information about a playlist.

Parameters:	id (str) – Playlist ID. index (int) – The numerical playlist index. is_current (bool) – If the playlist is currently selected. item_count (int) – The total number of items in the playlist. total_time (int) – The total playlist time in seconds.

id¶: Alias for field number 0

index¶: Alias for field number 1

is_current¶: Alias for field number 3

item_count¶: Alias for field number 4

title¶: Alias for field number 2

total_time¶: Alias for field number 5

class pyfoobeef.models.PlaylistItems(data, column_map=None)¶

An iterable and subscriptable class representing the items in a playlist.

Iterating or subscripting will return Columns objects.

find_item(case_sens: Optional[bool] = False, return_index: Optional[bool] = False, **kwargs) → Union[List[pyfoobeef.models.Columns], List[pyfoobeef.models.IndexItem]]¶

Search for a specific item.

Accepts attributes of the columns objects as argument names (i.e items.find_item(title=”The Song Title”, artist=”The Song Artist”)).

Parameters:	case_sens (Optional[bool]) – If true perform a case sensitive search. return_index (Optional[bool]) – If true returns the item’s index in the playlist.
Returns:	A list of either Columns objects or IndexItem namedtuples if return_index is true.
Return type:	Union[List[Columns], List[IndexItem]]

offset = None¶: The offset of the first item’s index for the items returned.

total_count = None¶: The total amount of items in the playlist.

class pyfoobeef.models.Playlists(data, column_map=None)¶

Represents the media player’s playlists.

Iterable and subscriptable.

find_playlist(title: Optional[str] = None, search_id: Optional[str] = None, find_last: Optional[bool] = False) → Optional[pyfoobeef.models.PlayerInfo]¶

Search for a specific playlist playlist.

Parameters:	title (Optional[str]) – The title of the playlist to find. search_id (Optional[str]) – The ID of the playlist to search for. find_last (Optional[bool]) – If true returns the last item found.
Returns:	A PlaylistInfo namedtuple if found else None.
Return type:	Optional[PlayerInfo]

class pyfoobeef.models.Volume(type, min, max, value, is_muted)¶

Represents information about the media player volume levels.

Parameters:	type (str) – The type of volume level in use (i.e. “db”) min (float) – The minimum volume level. max (float) – The maximum volume level. value (float) – The current volume level. is_muted (bool) – Player mute status.

is_muted¶: Alias for field number 4

max¶: Alias for field number 2

min¶: Alias for field number 1

type¶: Alias for field number 0

value¶: Alias for field number 3

Exceptions¶

exception pyfoobeef.ConnectError(original_exception: Exception)¶

Exception for errors relating to connecting to beefweb.

Parameters:	original_exception – The original exception made by the HTTP handler.

original_exception = None¶: The original exception made by the HTTP handler.

exception pyfoobeef.RequestError(response_code: int, response_data: dict)¶

Exception for errors relating to making requests to beefweb.

Parameters:	response_code – The HTTP status code returned by the request. response_data – The parsed data from beefwebs JSON response.

response_code = None¶: The HTTP status code returned by the request.

response_data = None¶: The parsed data from beefwebs JSON response.

The `Client` Class¶

The `AsyncClient` Class¶

The `EventListener` Class¶

Data Models¶

Exceptions¶

Table of Contents

Previous topic

This Page

The Client Class¶

The AsyncClient Class¶

The EventListener Class¶

Data Models¶

Exceptions¶

The `Client` Class¶

The `AsyncClient` Class¶

The `EventListener` Class¶