0
# Core Playback Control
1

2
Essential playback functionality providing complete control over media playback lifecycle, positioning, and basic player operations.
3

4
## Capabilities
5

6
### Player Initialization
7

8
Create and configure mpv player instances with custom options and logging.
9

10
```python { .api }
11
class MPV:
12
    def __init__(self, *extra_mpv_flags, log_handler=None, start_event_thread=True, loglevel=None, **extra_mpv_opts):
13
        """
14
        Initialize MPV player instance.
15

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

25
### Media Playback
26

27
Start playback of media files, URLs, and streaming sources.
28

29
```python { .api }
30
def play(self, filename: str):
31
    """
32
    Play a media file or URL.
33

34
    Parameters:
35
    - filename: Path to media file or URL to play
36

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

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

44
    Parameters:
45
    - filename: Path to media file or URL
46
    - mode: Load mode ('replace', 'append', 'append-play')
47
    - options: Additional file-specific options
48
    """
49
```
50

51
### Playback Control
52

53
Control playback state and position with precise seeking capabilities.
54

55
```python { .api }
56
def seek(self, amount: float, reference: str = "relative", precision: str = "keyframes"):
57
    """
58
    Seek to a specific position in the media.
59

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

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

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

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

75
def stop(self, keep_playlist: bool = False):
76
    """
77
    Stop playback.
78

79
    Parameters:
80
    - keep_playlist: If True, keep the current playlist position
81
    """
82
```
83

84
### Player Lifecycle
85

86
Manage player lifecycle and cleanup operations.
87

88
```python { .api }
89
def terminate(self):
90
    """Terminate the mpv player instance and free resources."""
91

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

96
    Parameters:
97
    - code: Exit code to return
98
    """
99

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

104
    Parameters:
105
    - code: Exit code to return
106
    """
107

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

111
@property
112
def core_shutdown(self) -> bool:
113
    """Whether the mpv core has been shutdown."""
114
```
115

116
### Log Level Control
117

118
Configure logging verbosity and message handling.
119

120
```python { .api }
121
def set_loglevel(self, level: str):
122
    """
123
    Set the log level.
124

125
    Parameters:
126
    - level: Log level ('fatal', 'error', 'warn', 'info', 'debug', 'trace')
127
    """
128
```
129

130
### Utility Commands
131

132
Advanced utility commands for system integration and state management.
133

134
```python { .api }
135
def run(self, command: str, *args):
136
    """
137
    Execute external system command.
138

139
    Parameters:
140
    - command: Command name to execute
141
    - args: Command arguments
142
    """
143

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

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

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

154
    Parameters:
155
    - mode: Rescan mode ('reselect', 'keep-selection')
156
    """
157

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

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

166
def enable_section(self, section: str):
167
    """
168
    Enable a configuration section.
169

170
    Parameters:
171
    - section: Section name to enable
172
    """
173

174
def disable_section(self, section: str):
175
    """
176
    Disable a configuration section.
177

178
    Parameters:
179
    - section: Section name to disable
180
    """
181
```
182

183
## Essential Properties
184

185
Core properties for controlling and monitoring playback state:
186

187
```python { .api }
188
# Playback state
189
pause: bool              # Pause/unpause playback
190
time_pos: float         # Current playback position in seconds
191
duration: float         # Total media duration in seconds
192
percent_pos: float      # Current position as percentage
193
speed: float           # Playback speed multiplier
194

195
# Media information
196
filename: str          # Currently loaded file
197
media_title: str       # Media title metadata
198
chapter: int          # Current chapter number
199
chapters: int         # Total number of chapters
200

201
# Audio/Video state
202
volume: float         # Audio volume (0-100)
203
mute: bool           # Audio mute state
204
fullscreen: bool     # Fullscreen mode
205
window_scale: float  # Window scaling factor
206
```
207

208
## Usage Examples
209

210
### Basic Playback
211

212
```python
213
import mpv
214
import time
215

216
# Create player
217
player = mpv.MPV()
218

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

222
# Wait for playback to start
223
player.wait_until_playing()
224

225
# Control playback
226
player.pause = True
227
time.sleep(2)
228
player.pause = False
229

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

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

239
player.terminate()
240
```
241

242
### Player Configuration
243

244
```python
245
# Create player with custom options
246
player = mpv.MPV(
247
    loglevel='info',
248
    input_default_bindings=True,
249
    input_vo_keyboard=True,
250
    osc=True,  # On-screen controller
251
    ytdl=True  # Enable youtube-dl
252
)
253

254
# Set properties during initialization
255
player = mpv.MPV(
256
    volume=50,
257
    fullscreen=True,
258
    loop_file='inf'
259
)
260
```
261

262
### Advanced Seeking
263

264
```python
265
# Precise frame-by-frame navigation
266
player.frame_step()      # Next frame
267
player.frame_back_step() # Previous frame
268

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

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

276
# Revert last seek
277
player.seek(120)
278
player.revert_seek()  # Go back to position before seek
279
```