Core Playback Control

class MPV:
    def __init__(self, *extra_mpv_flags, log_handler=None, start_event_thread=True, loglevel=None, **extra_mpv_opts):
        """
        Initialize MPV player instance.

        Parameters:
        - extra_mpv_flags: Additional command-line flags for mpv
        - log_handler: Custom log message handler function
        - start_event_thread: Whether to start event processing thread
        - loglevel: Log level ('fatal', 'error', 'warn', 'info', 'debug', 'trace')
        - extra_mpv_opts: Additional mpv options as keyword arguments
        """

def play(self, filename: str):
    """
    Play a media file or URL.

    Parameters:
    - filename: Path to media file or URL to play

    Note: This is equivalent to loadfile() with mode='replace'
    """

def loadfile(self, filename: str, mode: str = 'replace', **options):
    """
    Load a media file with specific mode and options.

    Parameters:
    - filename: Path to media file or URL
    - mode: Load mode ('replace', 'append', 'append-play')
    - options: Additional file-specific options
    """

def seek(self, amount: float, reference: str = "relative", precision: str = "keyframes"):
    """
    Seek to a specific position in the media.

    Parameters:
    - amount: Seek amount (seconds for time-based, percentage for percent-based)
    - reference: Reference point ('relative', 'absolute', 'percent+exact', 'percent')
    - precision: Seek precision ('keyframes', 'exact')
    """

def revert_seek(self):
    """Revert to the position before the last seek."""

def frame_step(self):
    """Step forward by exactly one frame."""

def frame_back_step(self):
    """Step backward by exactly one frame."""

def stop(self, keep_playlist: bool = False):
    """
    Stop playback.

    Parameters:
    - keep_playlist: If True, keep the current playlist position
    """

def terminate(self):
    """Terminate the mpv player instance and free resources."""

def quit(self, code: int = None):
    """
    Quit mpv with optional exit code.

    Parameters:
    - code: Exit code to return
    """

def quit_watch_later(self, code: int = None):
    """
    Quit mpv and save current position for later resumption.

    Parameters:
    - code: Exit code to return
    """

def check_core_alive(self):
    """Check if the mpv core is still alive."""

@property
def core_shutdown(self) -> bool:
    """Whether the mpv core has been shutdown."""

def set_loglevel(self, level: str):
    """
    Set the log level.

    Parameters:
    - level: Log level ('fatal', 'error', 'warn', 'info', 'debug', 'trace')
    """

def run(self, command: str, *args):
    """
    Execute external system command.

    Parameters:
    - command: Command name to execute
    - args: Command arguments
    """

def write_watch_later_config(self):
    """Save current playback position and settings for later resumption."""

def drop_buffers(self):
    """Drop internal video and audio buffers."""

def rescan_external_files(self, mode: str = 'reselect'):
    """
    Rescan for external subtitle and audio files.

    Parameters:
    - mode: Rescan mode ('reselect', 'keep-selection')
    """

def discnav(self, command: str):
    """
    DVD/Blu-ray disc navigation command.

    Parameters:
    - command: Navigation command ('up', 'down', 'left', 'right', 'ok', 'menu', etc.)
    """

def enable_section(self, section: str):
    """
    Enable a configuration section.

    Parameters:
    - section: Section name to enable
    """

def disable_section(self, section: str):
    """
    Disable a configuration section.

    Parameters:
    - section: Section name to disable
    """

# Playback state
pause: bool              # Pause/unpause playback
time_pos: float         # Current playback position in seconds
duration: float         # Total media duration in seconds
percent_pos: float      # Current position as percentage
speed: float           # Playback speed multiplier

# Media information
filename: str          # Currently loaded file
media_title: str       # Media title metadata
chapter: int          # Current chapter number
chapters: int         # Total number of chapters

# Audio/Video state
volume: float         # Audio volume (0-100)
mute: bool           # Audio mute state
fullscreen: bool     # Fullscreen mode
window_scale: float  # Window scaling factor

import mpv
import time

# Create player
player = mpv.MPV()

# Play a file
player.play('/path/to/video.mp4')

# Wait for playback to start
player.wait_until_playing()

# Control playback
player.pause = True
time.sleep(2)
player.pause = False

# Seek operations
player.seek(30)                    # Seek forward 30 seconds
player.seek(60, reference='absolute')  # Seek to 1 minute mark
player.seek(50, reference='percent')   # Seek to 50% position

# Check status
print(f"Position: {player.time_pos}/{player.duration}")
print(f"Paused: {player.pause}")

player.terminate()

# Create player with custom options
player = mpv.MPV(
    loglevel='info',
    input_default_bindings=True,
    input_vo_keyboard=True,
    osc=True,  # On-screen controller
    ytdl=True  # Enable youtube-dl
)

# Set properties during initialization
player = mpv.MPV(
    volume=50,
    fullscreen=True,
    loop_file='inf'
)

# Precise frame-by-frame navigation
player.frame_step()      # Next frame
player.frame_back_step() # Previous frame

# Different seek modes
player.seek(10, precision='exact')      # Exact seek (slower)
player.seek(10, precision='keyframes')  # Keyframe seek (faster, default)

# Percentage-based seeking
player.seek(25, reference='percent')  # Jump to 25% of duration

# Revert last seek
player.seek(120)
player.revert_seek()  # Go back to position before seek