sounds

Submodules

• sounds.auth
• sounds.base
• sounds.client
• sounds.constants
• sounds.cookies
• sounds.exceptions
• sounds.models
• sounds.parser
• sounds.personal
• sounds.requests
• sounds.schedule
• sounds.sounds_types
• sounds.stations
• sounds.streaming
• sounds.user
• sounds.utils

Exceptions

APIResponseError	Generic exception for the module
InvalidFormatError	Generic exception for the module
LoginFailedError	Generic exception for the module
NetworkError	Generic exception for the module
NotFoundError	Generic exception for the module

Classes

SoundsClient	A client to interact with the Sounds API
ContainerType	Create a collection of name/value pairs.
ImageType	An enum for valid image types for recipes
PlayStatus	Create a collection of name/value pairs.
URLs	/v2/networks - Provides the list of all the v2 networks
Category	Represents a content category.
Collection	Represents a collection container.
Container	Base container for organizing content - not directly playable.
LiveStation	Base class for actual playable content.
Menu	Represents a menu container with items.
MenuItem	Represents a menu item container.
PlayableItem	Base class for actual playable content.
Podcast	Represents a podcast container (holds episodes).
PodcastEpisode	Represents a playable podcast episode.
PromoItem	Base container for organizing content - not directly playable.
RadioClip	Represents a playable radio clip.
RadioSeries	Represents a radio series container (holds episodes).
RadioShow	Represents a playable radio show.
RecommendedMenuItem	Represents a recommended menu item.
Schedule	Represents a schedule for a given date.
ScheduleItem	Represents a scheduled program item.
Segment	Represents a segment within a stream.
Station	Represents a radio/media station.
StationSearchResult	Represents a search result showing a station. Keys are different enough to warrant a separate model
Stream	Represents a station stream.
MenuRecommendationOptions	Create a collection of name/value pairs.

Package Contents

class sounds.SoundsClient(username: str | None = None, password: str | None = None, session: aiohttp.ClientSession | None = None, cookie_file_location: str | pathlib.Path = COOKIE_FILE, timezone: datetime.tzinfo | None = None, logger: logging.Logger | None = None, log_level: int | None = None, mock_session: bool = False, **kwargs)

A client to interact with the Sounds API

username = None

password = None

login_details_provided = False

current_station: sounds.models.Station | None = None

current_stream: sounds.models.Stream | None = None

current_segment: sounds.models.Segment | None = None

timeout

mock_session = False

managing_session

cookie_store

auth

schedules

user

requests

streaming

stations

personal

setLogger(log_level=None)

async login() → bool

Signs into BBC Sounds.

Parameters:

• username – The username or email address to sign in with

• password – The password to sign in with

Returns:

True if successfully logged in, False otherwise

Return type:

bool

Raises:

• LoginFailedError – If the login fails for any reason

• UnauthorisedError – If the login is not authorised

save_cookies()

load_cookies()

property has_session_cookie: bool

Check if we have a cookie present.

async get_menu(include_local_stations: bool = False, recommendations: sounds.personal.MenuRecommendationOptions = MenuRecommendationOptions.INCLUDE)

Get the main Sounds menu.

async logout()

async close()

class sounds.ContainerType

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

• attribute access:

  >>> Color.RED
  <Color.RED: 1>
  

• value lookup:

  >>> Color(1)
  <Color.RED: 1>
  

• name lookup:

  >>> Color['RED']
  <Color.RED: 1>
  

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

BRAND = 'brand'

SERIES = 'series'

ITEM = 'container_item'

class sounds.ImageType

Bases: enum.Enum

An enum for valid image types for recipes

COLOUR = 'colour'

COLOUR_DEFAULT = 'colour_default'

BACKGROUND = 'background'

BLOCKS_COLOUR = 'blocks_colour'

BLOCKS_COLOUR_BLACK = 'blocks_colour_black'

BLOCKS_COLOUR_WHITE = 'blocks_colour_white'

class sounds.PlayStatus

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

• attribute access:

  >>> Color.RED
  <Color.RED: 1>
  

• value lookup:

  >>> Color(1)
  <Color.RED: 1>
  

• name lookup:

  >>> Color['RED']
  <Color.RED: 1>
  

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

STARTED = 'started'

PAUSED = 'paused'

ENDED = 'ended'

HEARTBEAT = 'heartbeat'

class sounds.URLs

Bases: enum.Enum

/v2/networks - Provides the list of all the v2 networks /v2/networks/playable - Provides the list of all the playable networks /v2/networks/{id}/playable - Provides the network playable item by network ID. <span>🎶</span> Green Day /radio/networks.json - All iPlayer Radio networks - contains business logic for masterbrand and service relationships /v2/services/{sid}/tracks/latest/playable - Retrieve list of tracks as playable items for a service <span>🎶</span> Deftones

LOGIN_START = 'https://session.bbc.co.uk/session?ptrt=https%3A%2F%2Fwww.bbc.co.uk%2Fsounds&context=iplayerradio...

LOGIN_START_I18N = 'https://account.bbc.com/auth?realm=%2F&clientId=Account&ptrt=https%3A%2F%2Fwww.bbc.com%2F&userOr...

LOGIN_BASE = 'https://account.bbc.com'

COOKIE_BASE = 'https://www.bbc.co.uk'

COOKIE_BASE_I18N = 'https://www.bbc.com'

JWT = 'https://rms.api.bbc.co.uk/v2/sign/token/{station_id}'

INTL_JWT = 'https://web-cdn.api.bbci.co.uk/xd/media-token?{id_type}={id}'

USER_INFO = 'https://www.bbc.co.uk/userinfo'

MEDIASET = 'https://open.live.bbc.co.uk/mediaselector/6/select/version/2.0/mediaset/pc/vpid/{station_id}/for...

EPISODE_MEDIASET = 'https://open.live.bbc.co.uk/mediaselector/6/select/version/2.0/mediaset/pc/vpid/{episode_id}'

NETWORKS_LIST = 'https://rms.api.bbc.co.uk/radio/networks.json'

STATIONS = 'https://rms.api.bbc.co.uk/v2/experience/inline/stations'

LIVE_STATION_DETAILS = 'https://rms.api.bbc.co.uk/v2/experience/inline/play/{station_id}'

STATION_DETAILS = 'https://rms.api.bbc.co.uk/v2/networks/{station_id}'

STATION_PLAYABLE_DETAILS = 'https://rms.api.bbc.co.uk/v2/networks/{station_id}/playable'

LIVE_STATION = 'https://www.bbc.co.uk/sounds/play/live:{station_id}'

NOW_PLAYING = 'https://rms.api.bbc.co.uk/v2/services/{station_id}/segments/latest?limit={limit}'

SCHEDULE = 'https://rms.api.bbc.co.uk/v2/experience/inline/schedules/{station_id}'

SCHEDULE_DATE = 'https://rms.api.bbc.co.uk/v2/experience/inline/schedules/{station_id}/{date}'

SEGMENTS = 'https://rms.api.bbc.co.uk/v2/versions/{vpid}/segments'

PLAYABLE_ITEMS_CONTAINER = 'https://rms.api.bbc.co.uk/v2/programmes/playable?container={pid}&sort=sequential'

CATEGORY_LATEST = 'https://rms.api.bbc.co.uk/v2/programmes/playable?category={category}&sort=-release_date&experien...

CATEGORY_POPULAR = 'https://rms.api.bbc.co.uk/v2/programmes/playable?category={category}&sort=popular&experience=domestic'

BROADCAST = 'https://rms.api.bbc.co.uk/v2/broadcasts/{pid}'

PID = 'https://rms.api.bbc.co.uk/v2/programmes/{pid}'

PID_PLAYABLE = 'https://rms.api.bbc.co.uk/v2/programmes/{pid}/playable'

CONTAINER_URL = 'https://rms.api.bbc.co.uk/v2/experience/inline/container/{urn}'

PLAYLIST = 'https://www.bbc.co.uk/programmes/{pid}/playlist.json'

COLLECTIONS_FULL = 'https://rms.api.bbc.co.uk/v2/collections/{pid}/members/container?experience=domestic&offset={off...

COLLECTIONS = 'https://rms.api.bbc.co.uk/v2/collections/{pid}/members/container?experience=domestic'

CURATIONS = 'https://rms.api.bbc.co.uk/v2/curations/{pid}/members/playable?experience=domestic'

EXPERIENCE_MENU = 'https://rms.api.bbc.co.uk/v2/my/experience/inline/listen'

SEARCH_URL = 'https://rms.api.bbc.co.uk/v2/experience/inline/search?q={search}'

SHOW_SEARCH_URL = 'https://rms.api.bbc.co.uk/v2/programmes/search/container?q={search}'

EPISOSDE_SEARCH_URL = 'https://rms.api.bbc.co.uk/v2/programmes/search/playable?q={search}'

PODCASTS = 'https://rms.api.bbc.co.uk/v2/experience/inline/speech'

MUSIC = 'https://rms.api.bbc.co.uk/v2/experience/inline/music'

NEWS = 'https://rms.api.bbc.co.uk/v2/experience/inline/container/urn:bbc:radio:category:news'

exception sounds.APIResponseError

Bases: SoundsException

Generic exception for the module

exception sounds.InvalidFormatError

Bases: SoundsException

Generic exception for the module

exception sounds.LoginFailedError

Bases: SoundsException

Generic exception for the module

exception sounds.NetworkError

Bases: SoundsException

Generic exception for the module

exception sounds.NotFoundError

Bases: SoundsException

Generic exception for the module

class sounds.Category

Bases: ImageContainer

Represents a content category.

class sounds.Collection

Bases: ImageContainer

Represents a collection container.

class sounds.Container

Bases: BaseObject, IdentifiableMixin

Base container for organizing content - not directly playable.

id: str

title: str | None = None

description: str | None = None

image_url: str | None = None

synopses: dict

titles: dict

urn: str | None = None

network: Network | None = None

sub_items: List[SoundsTypes] | None = None

class sounds.LiveStation

Bases: PlayableItem, IdentifiableMixin, ImageMixin

Base class for actual playable content.

local: bool = False

schedule: Schedule | None = None

class sounds.Menu

Bases: SerializableMixin

Represents a menu container with items.

sub_items: List[MenuItem] | Sequence[MenuItem] | None

get(key: str) → MenuItem | RecommendedMenuItem | None

Get a menu item by ID.

class sounds.MenuItem

Bases: ImageContainer

Represents a menu item container.

get(key: str) → CategoryItemContainer | Container | LiveStation | PodcastEpisode | RadioClip | RadioShow | Segment | ScheduleItem | StationSearchResult | None

Get a sub-menu item by ID.

class sounds.PlayableItem

Bases: BaseObject, IdentifiableMixin

Base class for actual playable content.

id: str

urn: str | None = None

pid: str | None = None

type: str | None = None

duration: dict | None = None

progress: dict | None = None

image_url: str | None = None

titles: dict

synopses: dict

network: Network | None = None

container: Container | None = None

start: datetime.datetime | None = None

end: datetime.datetime | None = None

release: dict | None = None

availability: dict | None = None

stream: str | None = None

is_live(timezone: zoneinfo.ZoneInfo | pytz.tzinfo.BaseTzInfo) → bool

has_already_aired(timezone: zoneinfo.ZoneInfo | pytz.tzinfo.BaseTzInfo) → bool

class sounds.Podcast

Bases: ImageContainer

Represents a podcast container (holds episodes).

class sounds.PodcastEpisode

Bases: PlayableItem, ImageMixin, IdentifiableMixin

Represents a playable podcast episode.

class sounds.PromoItem

Bases: Container

Base container for organizing content - not directly playable.

item: PlayableItem

class sounds.RadioClip

Bases: PlayableItem, TimedContent, ImageMixin, IdentifiableMixin

Represents a playable radio clip.

class sounds.RadioSeries

Bases: ImageContainer

Represents a radio series container (holds episodes).

class sounds.RadioShow

Bases: PlayableItem, TimedContent, ImageMixin, IdentifiableMixin

Represents a playable radio show.

property item_id

class sounds.RecommendedMenuItem

Bases: MenuItem

Represents a recommended menu item.

class sounds.Schedule

Bases: Container

Represents a schedule for a given date.

id: str

sub_items: List[ScheduleItem] | None

get_current_item(timezone: zoneinfo.ZoneInfo | pytz.tzinfo.BaseTzInfo = pytz.timezone('UTC')) → ScheduleItem | None

Get the currently airing schedule item.

class sounds.ScheduleItem

Bases: ImageMixin, PlayableItem

Represents a scheduled program item.

class sounds.Segment

Bases: SerializableMixin, ImageMixin

Represents a segment within a stream.

id: str

segment_type: str

titles: dict

image_url: str | None

offset: dict

uris: list[dict[str, str]]

property spotify_url

class sounds.Station

Bases: Container

Represents a radio/media station.

local: bool = False

stream: Stream | None = None

schedule: Schedule | None = None

class sounds.StationSearchResult

Bases: SerializableMixin, IdentifiableMixin

Represents a search result showing a station. Keys are different enough to warrant a separate model

id: str

type: str

urn: str

service_id: str

episode_image_url: str | None

station_image_url: str | None

station_name: str

title: str

short_synopsis: str

progress: dict[int, str]

duration: dict[int, str]

class sounds.Stream

Bases: TimedContent, SerializableMixin, ImageMixin

Represents a station stream.

id: str

uri: str

image_url: str | None

show_title: str

show_description: str

container: Any | None = None

property can_seek: bool

Indicates if the stream supports seeking.

class sounds.MenuRecommendationOptions

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

• attribute access:

  >>> Color.RED
  <Color.RED: 1>
  

• value lookup:

  >>> Color(1)
  <Color.RED: 1>
  

• name lookup:

  >>> Color['RED']
  <Color.RED: 1>
  

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

EXCLUDE = 'Exclude'

INCLUDE = 'Include'

ONLY = 'Only'