sounds
======

.. py:module:: sounds


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/sounds/auth/index
   /autoapi/sounds/base/index
   /autoapi/sounds/client/index
   /autoapi/sounds/constants/index
   /autoapi/sounds/exceptions/index
   /autoapi/sounds/models/index
   /autoapi/sounds/parser/index
   /autoapi/sounds/personal/index
   /autoapi/sounds/schedules/index
   /autoapi/sounds/sounds_types/index
   /autoapi/sounds/stations/index
   /autoapi/sounds/streaming/index
   /autoapi/sounds/utils/index


Exceptions
----------

.. autoapisummary::

   sounds.APIResponseError
   sounds.InvalidFormatError
   sounds.LoginFailedError
   sounds.NetworkError
   sounds.NotFoundError


Classes
-------

.. autoapisummary::

   sounds.SoundsClient
   sounds.ContainerType
   sounds.ImageType
   sounds.PlayStatus
   sounds.URLs
   sounds.Category
   sounds.Collection
   sounds.Container
   sounds.LiveStation
   sounds.Menu
   sounds.MenuItem
   sounds.PlayableItem
   sounds.Podcast
   sounds.PodcastEpisode
   sounds.PromoItem
   sounds.RadioClip
   sounds.RadioSeries
   sounds.RadioShow
   sounds.RecommendedMenuItem
   sounds.Schedule
   sounds.ScheduleItem
   sounds.Segment
   sounds.Station
   sounds.StationSearchResult
   sounds.Stream
   sounds.MenuRecommendationOptions


Package Contents
----------------

.. py:class:: SoundsClient(session: aiohttp.ClientSession | None = None, timezone: datetime.tzinfo | None = None, logger: logging.Logger | None = None, log_level: str | None = None, mock_session: bool = False, **kwargs)

   A client to interact with the Sounds API


   .. py:attribute:: current_station
      :type:  sounds.models.Station | None
      :value: None



   .. py:attribute:: current_stream
      :type:  sounds.models.Stream | None
      :value: None



   .. py:attribute:: current_segment
      :type:  sounds.models.Segment | None
      :value: None



   .. py:attribute:: timeout


   .. py:attribute:: mock_session
      :value: False



   .. py:attribute:: auth


   .. py:attribute:: schedules


   .. py:attribute:: streaming


   .. py:attribute:: stations


   .. py:attribute:: personal


   .. py:method:: setLogger(log_level=None)


   .. py:method:: close()
      :async:



.. py:class:: ContainerType(*args, **kwds)

   Bases: :py:obj:`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.


   .. py:attribute:: BRAND
      :value: 'brand'



   .. py:attribute:: SERIES
      :value: 'series'



   .. py:attribute:: ITEM
      :value: 'container_item'



.. py:class:: ImageType(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   An enum for valid image types for recipes


   .. py:attribute:: COLOUR
      :value: 'colour'



   .. py:attribute:: COLOUR_DEFAULT
      :value: 'colour_default'



   .. py:attribute:: BACKGROUND
      :value: 'background'



   .. py:attribute:: BLOCKS_COLOUR
      :value: 'blocks_colour'



   .. py:attribute:: BLOCKS_COLOUR_BLACK
      :value: 'blocks_colour_black'



   .. py:attribute:: BLOCKS_COLOUR_WHITE
      :value: 'blocks_colour_white'



.. py:class:: PlayStatus(*args, **kwds)

   Bases: :py:obj:`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.


   .. py:attribute:: STARTED
      :value: 'started'



   .. py:attribute:: PAUSED
      :value: 'paused'



   .. py:attribute:: ENDED
      :value: 'ended'



   .. py:attribute:: HEARTBEAT
      :value: 'heartbeat'



.. py:class:: URLs(*args, **kwds)

   Bases: :py:obj:`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



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



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



   .. py:attribute:: LOGIN_BASE
      :value: 'https://account.bbc.com'



   .. py:attribute:: COOKIE_BASE
      :value: 'https://www.bbc.co.uk'



   .. py:attribute:: COOKIE_BASE_I18N
      :value: 'https://www.bbc.com'



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



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



   .. py:attribute:: USER_INFO
      :value: 'https://www.bbc.co.uk/userinfo'



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



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



   .. py:attribute:: NETWORKS_LIST
      :value: 'https://rms.api.bbc.co.uk/radio/networks.json'



   .. py:attribute:: STATIONS
      :value: 'https://rms.api.bbc.co.uk/v2/experience/inline/stations'



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



   .. py:attribute:: PODCASTS
      :value: 'https://rms.api.bbc.co.uk/v2/experience/inline/speech'



   .. py:attribute:: MUSIC
      :value: 'https://rms.api.bbc.co.uk/v2/experience/inline/music'



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



.. py:exception:: APIResponseError

   Bases: :py:obj:`SoundsException`


   Generic exception for the module


.. py:exception:: InvalidFormatError

   Bases: :py:obj:`SoundsException`


   Generic exception for the module


.. py:exception:: LoginFailedError

   Bases: :py:obj:`SoundsException`


   Generic exception for the module


.. py:exception:: NetworkError

   Bases: :py:obj:`SoundsException`


   Generic exception for the module


.. py:exception:: NotFoundError

   Bases: :py:obj:`SoundsException`


   Generic exception for the module


.. py:class:: Category

   Bases: :py:obj:`Container`


   Represents a content category.


.. py:class:: Collection

   Bases: :py:obj:`Container`


   Represents a collection container.


.. py:class:: Container

   Bases: :py:obj:`BaseObject`


   Base container for organizing content - not directly playable.


   .. py:attribute:: id
      :type:  str


   .. py:attribute:: title
      :type:  Optional[str]
      :value: None



   .. py:attribute:: description
      :type:  Optional[str]
      :value: None



   .. py:attribute:: image_url
      :type:  Optional[str]
      :value: None



   .. py:attribute:: synopses
      :type:  Optional[dict]
      :value: None



   .. py:attribute:: titles
      :type:  Optional[dict]
      :value: None



   .. py:attribute:: urn
      :type:  Optional[str]
      :value: None



   .. py:attribute:: network
      :type:  Optional[Network]
      :value: None



   .. py:attribute:: sub_items
      :type:  Optional[List[SoundsTypes]]
      :value: None



   .. py:property:: item_id


.. py:class:: LiveStation

   Bases: :py:obj:`PlayableItem`


   Base class for actual playable content.


   .. py:attribute:: local
      :type:  bool
      :value: False



   .. py:attribute:: schedule
      :type:  Optional[Schedule]
      :value: None



   .. py:property:: item_id


.. py:class:: Menu

   Represents a menu container with items.


   .. py:attribute:: sub_items
      :type:  List[MenuItem] | Sequence[MenuItem] | None


   .. py:method:: get(key: str) -> Optional[MenuItem | RecommendedMenuItem]

      Get a menu item by ID.



.. py:class:: MenuItem

   Bases: :py:obj:`Container`


   Represents a menu item container.


.. py:class:: PlayableItem

   Bases: :py:obj:`BaseObject`


   Base class for actual playable content.


   .. py:attribute:: id
      :type:  str


   .. py:attribute:: urn
      :type:  Optional[str]
      :value: None



   .. py:attribute:: pid
      :type:  Optional[str]
      :value: None



   .. py:attribute:: type
      :type:  Optional[str]
      :value: None



   .. py:attribute:: duration
      :type:  Optional[dict]
      :value: None



   .. py:attribute:: progress
      :type:  Optional[dict]
      :value: None



   .. py:attribute:: image_url
      :type:  Optional[str]
      :value: None



   .. py:attribute:: titles
      :type:  Optional[dict]
      :value: None



   .. py:attribute:: synopses
      :type:  Optional[dict]
      :value: None



   .. py:attribute:: network
      :type:  Optional[Network]
      :value: None



   .. py:attribute:: container
      :type:  Optional[Container]
      :value: None



   .. py:attribute:: start
      :type:  Optional[datetime.datetime]
      :value: None



   .. py:attribute:: end
      :type:  Optional[datetime.datetime]
      :value: None



   .. py:attribute:: release
      :type:  Optional[dict]
      :value: None



   .. py:attribute:: availability
      :type:  Optional[dict]
      :value: None



   .. py:attribute:: stream
      :type:  Optional[str]
      :value: None



   .. py:property:: item_id


.. py:class:: Podcast

   Bases: :py:obj:`Container`


   Represents a podcast container (holds episodes).


.. py:class:: PodcastEpisode

   Bases: :py:obj:`PlayableItem`


   Represents a playable podcast episode.


.. py:class:: PromoItem

   Bases: :py:obj:`Container`


   Base container for organizing content - not directly playable.


   .. py:attribute:: item
      :type:  PlayableItem


.. py:class:: RadioClip

   Bases: :py:obj:`PlayableItem`, :py:obj:`TimedContent`


   Represents a playable radio clip.


.. py:class:: RadioSeries

   Bases: :py:obj:`Podcast`


   Represents a radio series container (holds episodes).


.. py:class:: RadioShow

   Bases: :py:obj:`PlayableItem`, :py:obj:`TimedContent`


   Represents a playable radio show.


   .. py:property:: item_id


.. py:class:: RecommendedMenuItem

   Bases: :py:obj:`MenuItem`


   Represents a recommended menu item.


.. py:class:: Schedule

   Bases: :py:obj:`Container`


   Represents a schedule for a given date.


   .. py:attribute:: id
      :type:  str


   .. py:method:: get_current_item(timezone: zoneinfo.ZoneInfo | pytz.tzinfo.BaseTzInfo = pytz.timezone('UTC')) -> Optional[ScheduleItem]

      Get the currently airing schedule item.



.. py:class:: ScheduleItem

   Bases: :py:obj:`PlayableItem`


   Represents a scheduled program item.


   .. py:attribute:: container
      :type:  Optional[Container]
      :value: None



   .. py:attribute:: stream
      :type:  Optional[str]
      :value: None



   .. py:method:: is_live(timezone: zoneinfo.ZoneInfo | pytz.tzinfo.BaseTzInfo) -> bool


   .. py:method:: has_already_aired(timezone: zoneinfo.ZoneInfo | pytz.tzinfo.BaseTzInfo) -> bool


.. py:class:: Segment

   Represents a segment within a stream.


   .. py:attribute:: id
      :type:  str


   .. py:attribute:: segment_type
      :type:  str


   .. py:attribute:: titles
      :type:  dict


   .. py:attribute:: image_url
      :type:  str | None


   .. py:attribute:: offset
      :type:  dict


.. py:class:: Station

   Bases: :py:obj:`Container`


   Represents a radio/media station.


   .. py:attribute:: local
      :type:  bool
      :value: False



   .. py:attribute:: stream
      :type:  Optional[Stream]
      :value: None



   .. py:attribute:: schedule
      :type:  Optional[Schedule]
      :value: None



.. py:class:: StationSearchResult

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


   .. py:attribute:: id
      :type:  str


   .. py:attribute:: type
      :type:  str


   .. py:attribute:: urn
      :type:  str


   .. py:attribute:: service_id
      :type:  str


   .. py:attribute:: episode_image_url
      :type:  str | None


   .. py:attribute:: station_image_url
      :type:  str | None


   .. py:attribute:: station_name
      :type:  str


   .. py:attribute:: title
      :type:  str


   .. py:attribute:: short_synopsis
      :type:  str


   .. py:attribute:: progress
      :type:  dict[int, str]


   .. py:attribute:: duration
      :type:  dict[int, str]


   .. py:property:: item_id


.. py:class:: Stream

   Bases: :py:obj:`TimedContent`


   Represents a station stream.


   .. py:attribute:: id
      :type:  str


   .. py:attribute:: uri
      :type:  str


   .. py:attribute:: image_url
      :type:  str | None


   .. py:attribute:: show_title
      :type:  str


   .. py:attribute:: show_description
      :type:  str


   .. py:attribute:: container
      :type:  Any | None
      :value: None



   .. py:property:: can_seek
      :type: bool


      Indicates if the stream supports seeking.



.. py:class:: MenuRecommendationOptions(*args, **kwds)

   Bases: :py:obj:`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.


   .. py:attribute:: EXCLUDE
      :value: 'Exclude'



   .. py:attribute:: INCLUDE
      :value: 'Include'



   .. py:attribute:: ONLY
      :value: 'Only'