py_now_playing

py_now_playing - A Python library for interacting with the Now Playing API. This library provides classes and functions to retrieve and manage information about the currently playing media, including playback status, media timeline, and media details.

Submodules

• py_now_playing.__main__
• py_now_playing.core
• py_now_playing.dataclasses

Classes

MediaTimeline	Timeline properties of the media
PlaybackInfo	Playback information for the current media session.
MediaPlaybackStatus	Playback status of the media
MediaPlaybackType	Type of media playback.
MediaPlaybackAutoRepeatMode	Auto-repeat enum mode for media playback.
PyNowPlaying	Playback Controls Class
MediaInfo	Media Information Class

Package Contents

class py_now_playing.MediaTimeline

Timeline properties of the media This class holds details about the media timeline such as start time, end time, maximum seek time, current position, minimum seek time, and the last updated time.

start_time: datetime.timedelta | None = None

end_time: datetime.timedelta | None = None

max_seek_time: datetime.timedelta | None = None

position: datetime.timedelta | None = None

min_seek_time: datetime.timedelta | None = None

last_updated_time: datetime.datetime | None = None

class py_now_playing.PlaybackInfo

Playback information for the current media session. This class holds details such as the playback type, status, rate, auto-repeat mode, and shuffle state. Attributes:

playback_type: Type of media playback (e.g., music, video, image) playback_status: Current status of the media playback playback_rate: Rate at which the media is being played (1.0 for normal speed) auto_repeat_mode: Auto-repeat mode for the media playback is_shuffle_active: Whether shuffle mode is active

playback_type: MediaPlaybackType | None = None

playback_status: MediaPlaybackStatus | None = None

playback_rate: float | None = None

auto_repeat_mode: MediaPlaybackAutoRepeatMode | None = None

is_shuffle_active: bool | None = None

controls: py_now_playing.dataclasses.enabled_controls.EnabledControls | None = None

class py_now_playing.MediaPlaybackStatus

Bases: enum.IntEnum

Playback status of the media

CLOSED = 0

OPENED = 1

CHANGING = 2

STOPPED = 3

PLAYING = 4

PAUSED = 5

class py_now_playing.MediaPlaybackType

Bases: enum.IntEnum

Type of media playback.

UNKNOWN = 0

MUSIC = 1

VIDEO = 2

IMAGE = 3

class py_now_playing.MediaPlaybackAutoRepeatMode

Bases: enum.IntEnum

Auto-repeat enum mode for media playback.

NONE = 0

TRACK = 1

LIST = 2

class py_now_playing.PyNowPlaying(*args, **kwargs)

Playback Controls Class

This class provides methods to control media playback and retrieve media information. It interacts with the Windows Media Control API to manage playback sessions.

Attributes:

aumid (str): The AppUserModelId of the application. _manager (MediaManager): The MediaManager instance for managing media sessions.

classmethod create(aumid: str)

Async:

Async factory method to initialize PyNowPlaying with a MediaManager.

Args:

aumid (str): The AppUserModelId of the application.

Returns:

PyNowPlaying: An initialized instance with MediaManager ready.

classmethod _init(aumid: str, media_manager: winrt.windows.media.control.GlobalSystemMediaTransportControlsSessionManager)

Initializes the PyNowPlaying class.

Args:

aumid (str): The AppUserModelId of the application. media_manager (MediaManager): The MediaManager instance.

Raises:

ValueError: If aumid is None.

async pause() → bool

Pause the media

Returns:

bool: True if successful, False

async play() → bool

Play the media

Returns:

bool: True if successful, False

async toggle_play_pause() → bool

Toggle play/pause the media

Returns:

bool: True if successful, False

async stop() → bool

Stop the media

Returns:

bool: True if successful, False

async record() → bool

Tell the application to record

Returns:

bool: True if successful, False

async rewind() → bool

Rewind the media

Returns:

bool: True if successful, False

async fast_forward() → bool

Fast forward the media

Returns:

bool: True if successful, False

async next_track() → bool

Skip to the next track

Returns:

bool: True if successful, False

async previous_track() → bool

Skip to the previous track

Returns:

bool: True if successful, False

async change_playback_rate(rate: float) → bool

Changes the playback rate for supported apps/media.

Args:

rate (float): The new playback rate.

Returns:

bool: True if successful, False

async change_shuffle_active(state: bool) → bool

Changes the shuffle active state.

Args:

state (bool): The new shuffle active state.

Returns:

bool: True if successful, False

async change_auto_repeat_mode(mode: int) → bool

Changes the auto repeat mode.

Args:

mode (int): The new auto repeat mode. 0 = None, 1 = Track, 2 = List

Returns:

bool: True if successful, False

async seek(position: int) → bool

Changes the playback position (Time Elapsed)

Args:

position (int): The new playback position in seconds.

Returns:

bool: True if successful, False

async channel_up() → bool

Sends a channel up command to the media session.

Returns:

bool: True if successful, False

async channel_down() → bool

Sends a channel down command to the media session.

Returns:

bool: True if successful, False

async get_timeline_properties() → py_now_playing.dataclasses.media_timeline.MediaTimeline | None

Gets the timeline properties of the media.

Note:

Windows updates the Media Timeline information at it’s own pace, so if you want a live position marker, use get_interpolated_timeline_properties()

Returns:

MediaTimeline: The timeline properties of the media.

async get_interpolated_timeline_properties() → py_now_playing.dataclasses.media_timeline.MediaTimeline | None

Gets the interpolated timeline properties of the media.

Note:

MediaTimeline.last_updated_time is the last update by WinRT, not since the update of this function.

Returns:

MediaTimeline: The interpolated timeline properties of the media.

async get_thumbnail() → PIL.Image.Image | None

Gets the thumbnail of the media.

Returns:

Image: The thumbnail of the media as a PIL Image.

async get_media_info() → py_now_playing.dataclasses.media_info.MediaInfo | None

Gets the media info of the media.

Returns:

MediaInfo: The media info of the media.

async get_playback_info() → py_now_playing.dataclasses.playback_info.PlaybackInfo | None

Gets the playback info of the media.

Returns:

PlaybackInfo: The playback info of the media.

async thumbnail_to_image(thumbnail) → PIL.Image.Image | None

Converts a thumbnail to a PIL Image.

Args:

thumbnail: The thumbnail to convert.

Returns:

Image: The PIL Image.

static get_active_app_user_model_ids() → list[dict[str, str]]

Async:

Gets AppUserModelIds of apps which are actively playing media.

Returns:

list: The active AppUserModelIds in the format [{Name, AppID}, …]

static get_all_aumids_by_name(name: str) → list[str] | None

Async:

Gets the AUMID by the name of the app. Note that this gets the first match of the app name. If there are multiple apps with the same name, it will return the first one installed on your system, not the one currently running.

Args:

name (str): The name of the app.

Returns:

list[str]: A list of AppUserModelIds that match the name. None: If no matches are found.

_internal_playback_info_changed_callback(sender, args)

Internal callback for playback info changes.

_internal_timeline_properties_changed_callback(sender, args)

Internal callback for timeline properties changes.

_internal_media_properties_changed_callback(sender, args)

Internal callback for media properties changes.

register_playback_info_changed_callback(callback: Callable[[winrt.windows.media.control.GlobalSystemMediaTransportControlsSession, py_now_playing.dataclasses.playback_info.PlaybackInfo], None]) → None

Registers a callback for playback info changes.

Args:

callback: The callback function.

register_timeline_properties_changed_callback(callback: Callable[[winrt.windows.media.control.GlobalSystemMediaTransportControlsSession, py_now_playing.dataclasses.media_timeline.MediaTimeline], None]) → None

Registers a callback for timeline properties changes.

Args:

callback: The callback function.

register_media_properties_changed_callback(callback: Callable[[winrt.windows.media.control.GlobalSystemMediaTransportControlsSession, py_now_playing.dataclasses.media_info.MediaInfo], None]) → None

Registers a callback for media properties changes.

Args:

callback: The callback function.

deregister_playback_info_changed_callback() → None

Deregisters the playback info changed callback.

deregister_timeline_properties_changed_callback() → None

Deregisters the timeline properties changed callback.

deregister_media_properties_changed_callback() → None

Deregisters the media properties changed callback.

class py_now_playing.MediaInfo

Media Information Class This class holds details about the currently playing media, including artist, title, album information, track number, genres, playback type, and thumbnail image.

Attributes:

artist: Name of the artist title: Title of the media album_title: Title of the album album_artist: Artist of the album album_track_count: Number of tracks in the album track_number: Track number in the album genres: List of genres associated with the media playback_type: Type of playback (e.g., music, video) thumbnail: Thumbnail image of the media

artist: str | None = None

title: str | None = None

album_title: str | None = None

album_artist: str | None = None

album_track_count: int | None = None

track_number: int | None = None

genres: list | None = None

playback_type: str | None = None

thumbnail: PIL.Image.Image | None = None