0
# Property Management
1

2
Complete access to mpv's property system with observation capabilities, specialized accessors, and type conversion. The property system provides the primary interface for configuring and monitoring all aspects of mpv's behavior.
3

4
## Capabilities
5

6
### Property Access
7

8
Direct access to mpv properties using attribute syntax, dictionary-like access, or specialized property proxies.
9

10
```python { .api }
11
class MPV:
12
    def __getattr__(self, name):
13
        """Get property value using attribute access (e.g., player.volume)."""
14

15
    def __setattr__(self, name, value):
16
        """Set property value using attribute access (e.g., player.volume = 50)."""
17

18
    def __getitem__(self, name: str, file_local: bool = False):
19
        """
20
        Get property value using dictionary-like access.
21

22
        Parameters:
23
        - name: Property name
24
        - file_local: Whether to access file-local variant
25
        """
26

27
    def __setitem__(self, name: str, value, file_local: bool = False):
28
        """
29
        Set property value using dictionary-like access.
30

31
        Parameters:
32
        - name: Property name
33
        - value: Property value
34
        - file_local: Whether to set file-local variant
35
        """
36

37
    def __iter__(self):
38
        """Iterate over all available property names."""
39

40
    def __dir__(self):
41
        """List all available properties for tab completion."""
42

43
    @property
44
    def properties(self) -> dict:
45
        """Dictionary containing all current property values."""
46
```
47

48
### Property Proxies
49

50
Specialized property accessors for different use cases and data formatting.
51

52
```python { .api }
53
@property
54
def osd(self) -> 'PropertyProxy':
55
    """Property proxy that formats values for OSD display."""
56

57
@property
58
def file_local(self) -> 'PropertyProxy':
59
    """Property proxy for file-local property variants."""
60

61
@property
62
def raw(self) -> 'PropertyProxy':
63
    """Property proxy that returns raw property values without type conversion."""
64

65
@property
66
def strict(self) -> 'PropertyProxy':
67
    """Property proxy with strict type checking and error handling."""
68

69
@property
70
def lazy(self) -> 'PropertyProxy':
71
    """Property proxy with lazy evaluation and error tolerance."""
72
```
73

74
### Property Observation
75

76
Monitor property changes with callback functions and decorators.
77

78
```python { .api }
79
def observe_property(self, name: str, handler):
80
    """
81
    Register a callback to monitor property changes.
82

83
    Parameters:
84
    - name: Property name to observe
85
    - handler: Callback function(name, value)
86
    """
87

88
def property_observer(self, name: str):
89
    """
90
    Decorator for registering property change observers.
91

92
    Parameters:
93
    - name: Property name to observe
94

95
    Returns:
96
    Decorator function for callback registration
97
    """
98

99
def unobserve_property(self, name: str, handler):
100
    """
101
    Remove a property change observer.
102

103
    Parameters:
104
    - name: Property name
105
    - handler: Handler function to remove
106
    """
107

108
def unobserve_all_properties(self, handler):
109
    """
110
    Remove a handler from all observed properties.
111

112
    Parameters:
113
    - handler: Handler function to remove from all properties
114
    """
115

116
@property
117
def property_list(self) -> list:
118
    """List of all available property names."""
119

120
@property
121
def options(self) -> list:
122
    """List of all available option names."""
123
```
124

125
### Property Operations
126

127
Advanced property manipulation including arithmetic operations and cycling.
128

129
```python { .api }
130
def property_add(self, name: str, value: float = 1):
131
    """
132
    Add a value to a numeric property.
133

134
    Parameters:
135
    - name: Property name
136
    - value: Value to add (default: 1)
137
    """
138

139
def property_multiply(self, name: str, factor: float):
140
    """
141
    Multiply a numeric property by a factor.
142

143
    Parameters:
144
    - name: Property name
145
    - factor: Multiplication factor
146
    """
147

148
def cycle(self, name: str, direction: str = 'up'):
149
    """
150
    Cycle through property values.
151

152
    Parameters:
153
    - name: Property name
154
    - direction: Cycle direction ('up' or 'down')
155
    """
156
```
157

158
### Property Information
159

160
Access metadata about available properties and their characteristics.
161

162
```python { .api }
163
def option_info(self, name: str) -> dict:
164
    """
165
    Get detailed information about a property/option.
166

167
    Parameters:
168
    - name: Property name
169

170
    Returns:
171
    Dictionary with property metadata including type, range, default value
172
    """
173
```
174

175
## Common Properties
176

177
### Playback Properties
178

179
```python { .api }
180
# Playback control
181
pause: bool                    # Pause state
182
time_pos: float               # Current position in seconds
183
duration: float               # Total duration in seconds
184
percent_pos: float            # Position as percentage (0-100)
185
speed: float                  # Playback speed multiplier
186
loop_file: str               # File looping mode ('no', 'inf', or number)
187
loop_playlist: str           # Playlist looping mode
188

189
# Chapter navigation
190
chapter: int                 # Current chapter number (0-based)
191
chapters: int               # Total number of chapters
192
chapter_list: list          # List of chapter information
193

194
# Seeking behavior
195
hr_seek: str                # High-resolution seek mode
196
hr_seek_framedrop: bool     # Frame dropping during seeks
197
```
198

199
### Audio Properties
200

201
```python { .api }
202
# Audio control
203
volume: float               # Volume level (0-100)
204
volume_max: float          # Maximum volume limit
205
mute: bool                 # Mute state
206
audio_delay: float         # Audio delay in seconds
207
speed: float              # Audio/video speed
208

209
# Audio track selection
210
aid: int                  # Active audio track ID
211
audio: int               # Audio track by index
212
audio_device: str        # Audio output device
213
af: str                  # Audio filter chain
214

215
# Audio information
216
audio_bitrate: float     # Current audio bitrate
217
audio_channels: int      # Number of audio channels
218
audio_codec: str         # Audio codec name
219
```
220

221
### Video Properties
222

223
```python { .api }
224
# Video control
225
brightness: int           # Video brightness (-100 to 100)
226
contrast: int            # Video contrast (-100 to 100)
227
saturation: int          # Video saturation (-100 to 100)
228
gamma: int               # Video gamma (-100 to 100)
229
hue: int                 # Video hue (-100 to 100)
230

231
# Video track selection
232
vid: int                 # Active video track ID
233
video: int              # Video track by index
234
vf: str                 # Video filter chain
235

236
# Video information
237
video_bitrate: float    # Current video bitrate
238
width: int              # Video width in pixels
239
height: int             # Video height in pixels
240
fps: float              # Video frame rate
241
video_codec: str        # Video codec name
242
```
243

244
### Subtitle Properties
245

246
```python { .api }
247
# Subtitle control
248
sid: int                # Active subtitle track ID
249
sub: int               # Subtitle track by index
250
sub_visibility: bool   # Subtitle visibility
251
sub_delay: float       # Subtitle delay in seconds
252
sub_scale: float       # Subtitle scaling factor
253

254
# Subtitle positioning
255
sub_pos: int           # Subtitle position (0-100)
256
sub_align_x: str       # Horizontal alignment
257
sub_align_y: str       # Vertical alignment
258

259
# Subtitle information
260
sub_text: str          # Current subtitle text
261
```
262

263
### Window and Display Properties
264

265
```python { .api }
266
# Window control
267
fullscreen: bool        # Fullscreen mode
268
window_scale: float     # Window scaling factor
269
window_minimized: bool  # Window minimized state
270
window_maximized: bool  # Window maximized state
271
ontop: bool            # Always on top
272

273
# Display information
274
display_fps: float      # Display refresh rate
275
display_width: int      # Display width
276
display_height: int     # Display height
277
```
278

279
## Usage Examples
280

281
### Basic Property Access
282

283
```python
284
import mpv
285

286
player = mpv.MPV()
287
player.play('/path/to/video.mp4')
288

289
# Attribute-style access
290
print(f"Volume: {player.volume}")
291
player.volume = 75
292
player.pause = True
293

294
# Dictionary-style access
295
print(f"Duration: {player['duration']}")
296
player['speed'] = 1.5
297

298
# Using property proxies
299
player.osd.volume = 80  # Shows volume in OSD
300
player.file_local.speed = 2.0  # File-local speed setting
301
```
302

303
### Property Observation
304

305
```python
306
# Using decorator
307
@player.property_observer('time-pos')
308
def position_changed(name, value):
309
    if value is not None:
310
        print(f"Position: {value:.2f} seconds")
311

312
# Using method
313
def volume_changed(name, value):
314
    print(f"Volume changed to: {value}")
315

316
player.observe_property('volume', volume_changed)
317

318
# Multiple properties with one handler
319
def media_info_changed(name, value):
320
    print(f"{name}: {value}")
321

322
for prop in ['width', 'height', 'fps', 'video-codec']:
323
    player.observe_property(prop, media_info_changed)
324
```
325

326
### Advanced Property Operations
327

328
```python
329
# Arithmetic operations
330
player.property_add('volume', 10)      # Increase volume by 10
331
player.property_add('volume', -5)      # Decrease volume by 5
332
player.property_multiply('speed', 1.5) # 1.5x speed
333

334
# Cycling through values
335
player.cycle('fullscreen')    # Toggle fullscreen
336
player.cycle('mute')          # Toggle mute
337
player.cycle('audio')         # Switch audio track
338

339
# Property information
340
volume_info = player.option_info('volume')
341
print(f"Volume range: {volume_info['min']} - {volume_info['max']}")
342
print(f"Default volume: {volume_info['default']}")
343
```
344

345
### Property Monitoring
346

347
```python
348
# Monitor multiple properties
349
@player.property_observer('pause')
350
def pause_handler(name, value):
351
    state = "paused" if value else "playing"
352
    print(f"Playback {state}")
353

354
@player.property_observer('eof-reached')
355
def eof_handler(name, value):
356
    if value:
357
        print("End of file reached")
358

359
# Get all properties
360
all_props = dict(player.properties)
361
print(f"Total properties: {len(all_props)}")
362

363
# List available properties
364
available = list(player)
365
print(f"Available properties: {len(available)}")
366
```
367

368
### File-Local Properties
369

370
```python
371
# Set properties that only apply to current file
372
player.file_local.volume = 80        # Volume for this file only
373
player.file_local.brightness = 10    # Brightness for this file only
374

375
# Access file-local variants
376
print(f"File-local volume: {player.file_local.volume}")
377
print(f"Global volume: {player.volume}")
378
```