Source code for miniworlds.worlds.manager.music_manager

from typing import Optional
import miniworlds.base.app as app_mod



class MusicManager:
    """Controls background music playback for a world.

    Access via `world.music`.

    Examples:
        ::

            world.music.play("assets/theme.mp3")
            world.music.set_volume(80)
            world.music.pause()
            world.music.stop()
    """

    def __init__(self, app: app_mod.App):
        # Store a reference to the app and its internal music manager
        self.app: app_mod.App = app
        self.music_manager = self.app.music_manager



    def pause(self) -> None:
        """Pause the currently playing music.

        Examples:
            ::

                world.music.pause()
        """
        self.music_manager.pause()




    def is_playing(self) -> bool:
        """Return whether music is currently playing.

        Returns:
            `True` if music is playing.

        Examples:
            ::

                if world.music.is_playing():
                    print("Music is playing")
        """
        return self.music_manager.is_playing()




    def get_path(self) -> str:
        """Return the path of the currently loaded music file.

        Returns:
            Path to the current music file.

        Examples:
            ::

                current_path = world.music.get_path()
        """
        return self.music_manager.path




    def play(self, path: Optional[str] = None, loop: int = -1) -> None:
        """Play a music file.

        Args:
            path: Path to the music file. If None, replays the last used music.
            loop: Number of times to repeat the music. Use -1 for infinite looping.

        Examples:
            ::

                world.music.play("assets/music/theme.mp3")
                world.music.play("assets/music/loop.wav", loop=2)
                world.music.play()
        """
        self.music_manager.play_music(path, loop)




    def stop(self) -> None:
        """Stop the currently playing music.

        Examples:
            ::

                world.music.stop()
        """
        self.music_manager.stop_music()




    def set_volume(self, volume: float) -> None:
        """Set the playback volume.

        Args:
            volume: Volume level from 0.0 (silent) to 100.0 (maximum).

        Raises:
            ValueError: If volume is outside the 0-100 range.

        Examples:
            ::

                world.music.set_volume(80)
        """
        if not 0.0 <= volume <= 100.0:
            raise ValueError("Volume must be between 0 and 100.")
        self.music_manager.set_volume(volume)




    def get_volume(self) -> float:
        """Return the current playback volume.

        Returns:
            Volume level as a float between 0.0 and 100.0.

        Examples:
            ::

                current_volume = world.music.get_volume()
        """
        return self.music_manager.get_volume()




    def toggle_pause(self) -> None:
        """Toggle the pause state of the music.

        Note:
            This assumes that the internal music manager has a `resume()` method.

        Examples:
            ::

                world.music.toggle_pause()
        """
        if self.is_playing():
            self.pause()
        else:
            # Resume playback if previously paused
            self.music_manager.resume()