Skip to content

add support for fetching loudness levels of audio streams #1529

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+25 −0
Open

add support for fetching loudness levels of audio streams #1529

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1eb80e4
add support for fetching loudness levels of audio streams
bastiaanterhorst Jun 12, 2025
2e9fdff
Add test for levels
bastiaanterhorst Jun 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions plexapi/media.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -433,10 +433,34 @@ def setSelected(self):
"""
return self._parent().setSelectedAudioStream(self)

def levels(self, subSample=128):
""" Load time series loudness levels.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
""" Load time series loudness levels.
""" Returns a list of :class:`~plexapi.media.Level` objects for this AudioStream.
Only available for Tracks which have been analyzed for loudness.


Attributes:
subSample: (int): the number of loudness segments to load
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
subSample: (int): the number of loudness segments to load
subSample (int): The number of loudness samples to return. Default 128.

"""

key = f'/library/streams/{self.id}/levels'
params = {'subsample': subSample}

levels = self.fetchItems(ekey=key, cls=Level, params=params)
return levels
Comment on lines +442 to +447
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
key = f'/library/streams/{self.id}/levels'
params = {'subsample': subSample}
levels = self.fetchItems(ekey=key, cls=Level, params=params)
return levels
key = f'/library/streams/{self.id}/levels'
params = {'subsample': subSample}
return self.fetchItems(key, params=params)


@deprecated('Use "setSelected" instead.')
def setDefault(self):
return self.setSelected()

@utils.registerPlexObject
class Level(PlexObject):
""" Represents an instance of loudness for an audio stream.

Attributes:
loudness (float): loudness level in db
"""
def _loadData(self, data):
""" Load attribute values from Plex XML response. """
self.loudness = data.attrib.get('v')

Comment on lines +453 to +463
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move to the bottom of the file.

Suggested change
@utils.registerPlexObject
class Level(PlexObject):
""" Represents an instance of loudness for an audio stream.
Attributes:
loudness (float): loudness level in db
"""
def _loadData(self, data):
""" Load attribute values from Plex XML response. """
self.loudness = data.attrib.get('v')
@utils.registerPlexObject
class Level(PlexObject):
""" Represents a single loudness Level sample for an AudioStream.
Attributes:
loudness (float): Loudness level value
"""
def _loadData(self, data):
""" Load attribute values from Plex XML response. """
self.loudness = utils.cast(float, data.attrib.get('v'))


@utils.registerPlexObject
class SubtitleStream(MediaPartStream):
Expand Down
1 change: 1 addition & 0 deletions tests/test_audio.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,7 @@ def test_audio_Track_attrs(album):
assert stream.lra is None
assert stream.peak is None
assert stream.startRamp is None
assert len(stream.levels(subSample=32)) == 32
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
assert len(stream.levels(subSample=32)) == 32
if stream.loudness is not None:
assert len(stream.levels(subSample=32)) == 32



def test_audio_Track_album(album):
Expand Down