summaryrefslogtreecommitdiffstats
path: root/DOCS/man/input.rst
blob: 2b3e2a3795b171b071896149a5ac408c2d31f315 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
COMMAND INTERFACE
=================

The mpv core can be controlled with commands and properties. A number of ways
to interact with the player use them: key bindings (``input.conf``), OSD
(showing information with properties), JSON IPC, the client API (``libmpv``),
and the classic slave mode.

input.conf
----------

The input.conf file consists of a list of key bindings, for example::

    s screenshot      # take a screenshot with the s key
    LEFT seek 15      # map the left-arrow key to seeking forward by 15 seconds

Each line maps a key to an input command. Keys are specified with their literal
value (upper case if combined with ``Shift``), or a name for special keys. For
example, ``a`` maps to the ``a`` key without shift, and ``A`` maps to ``a``
with shift.

The file is located in the mpv configuration directory (normally at
``~/.config/mpv/input.conf`` depending on platform). The default bindings are
defined here::

    https://github.com/mpv-player/mpv/blob/master/etc/input.conf

A list of special keys can be obtained with

    ``mpv --input-keylist``

In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``::

    ctrl+q quit

**mpv** can be started in input test mode, which displays key bindings and the
commands they're bound to on the OSD, instead of executing the commands::

    mpv --input-test --force-window --idle

(Only closing the window will make **mpv** exit, pressing normal keys will
merely display the binding, even if mapped to quit.)

General Input Command Syntax
----------------------------

``[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] [<prefixes>] <command> (<argument>)* [; <command>]``

Note that by default, the right Alt key can be used to create special
characters, and thus does not register as a modifier. The option
``--no-input-right-alt-gr`` changes this behavior.

Newlines always start a new binding. ``#`` starts a comment (outside of quoted
string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used.

``<key>`` is either the literal character the key produces (ASCII or Unicode
character), or a symbolic name (as printed by ``--input-keylist``).

``<section>`` (braced with ``{`` and ``}``) is the input section for this
command.

Arguments are separated by whitespace. This applies even to string arguments.
For this reason, string arguments should be quoted with ``"``. Inside quotes,
C-style escaping can be used.

You can bind multiple commands to one key. For example:

| a show-text "command 1" ; show-text "command 2"

It's also possible to bind a command to a sequence of keys:

| a-b-c show-text "command run after a, b, c have been pressed"

(This is not shown in the general command syntax.)

If ``a`` or ``a-b`` or ``b`` are already bound, this will run the first command
that matches, and the multi-key command will never be called. Intermediate keys
can be remapped to ``ignore`` in order to avoid this issue. The maximum number
of (non-modifier) keys for combinations is currently 4.

List of Input Commands
----------------------

``ignore``
    Use this to "block" keys that should be unbound, and do nothing. Useful for
    disabling default bindings, without disabling all bindings with
    ``--no-input-default-bindings``.

``seek <seconds> [relative|absolute|absolute-percent|relative-percent|exact|keyframes]``
    Change the playback position. By default, seeks by a relative amount of
    seconds.

    The second argument consists of flags controlling the seek mode:

    relative (default)
        Seek relative to current position (a negative value seeks backwards).
    absolute
        Seek to a given time (a negative value starts from the end of the file).
    absolute-percent
        Seek to a given percent position.
    relative-percent
        Seek relative to current position in percent.
    keyframes
        Always restart playback at keyframe boundaries (fast).
    exact
        Always do exact/hr/precise seeks (slow).

    Multiple flags can be combined, e.g.: ``absolute+keyframes``.

    By default, ``keyframes`` is used for relative seeks, and ``exact`` is used
    for absolute seeks.

    Before mpv 0.9, the ``keyframes`` and ``exact`` flags had to be passed as
    3rd parameter (essentially using a space instead of ``+``). The 3rd
    parameter is still parsed, but is considered deprecated.

``revert-seek [mode]``
    Undoes the ``seek`` command, and some other commands that seek (but not
    necessarily all of them). Calling this command once will jump to the
    playback position before the seek. Calling it a second time undoes the
    ``revert-seek`` command itself. This only works within a single file.

    The first argument is optional, and can change the behavior:

    mark
        Mark the current time position. The next normal ``revert-seek`` command
        will seek back to this point, no matter how many seeks happened since
        last time.

    Using it without any arguments gives you the default behavior.

``frame-step``
    Play one frame, then pause. Does nothing with audio-only playback.

``frame-back-step``
    Go back by one frame, then pause. Note that this can be very slow (it tries
    to be precise, not fast), and sometimes fails to behave as expected. How
    well this works depends on whether precise seeking works correctly (e.g.
    see the ``--hr-seek-demuxer-offset`` option). Video filters or other video
    post-processing that modifies timing of frames (e.g. deinterlacing) should
    usually work, but might make backstepping silently behave incorrectly in
    corner cases. Using ``--hr-seek-framedrop=no`` should help, although it
    might make precise seeking slower.

    This does not work with audio-only playback.

``set <property> "<value>"``
    Set the given property to the given value.

``add <property> [<value>]``
    Add the given value to the property. On overflow or underflow, clamp the
    property to the maximum. If ``<value>`` is omitted, assume ``1``.

``cycle <property> [up|down]``
    Cycle the given property. ``up`` and ``down`` set the cycle direction. On
    overflow, set the property back to the minimum, on underflow set it to the
    maximum. If ``up`` or ``down`` is omitted, assume ``up``.

``multiply <property> <factor>``
    Multiplies the value of a property with the numeric factor.

``screenshot [subtitles|video|window|single|each-frame]``
    Take a screenshot.

    Multiple flags are available (some can be combined with ``+``):

    <subtitles> (default)
        Save the video image, in its original resolution, and with subtitles.
        Some video outputs may still include the OSD in the output under certain
        circumstances.
    <video>
        Like ``subtitles``, but typically without OSD or subtitles. The exact
        behavior depends on the selected video output.
    <window>
        Save the contents of the mpv window. Typically scaled, with OSD and
        subtitles. The exact behavior depends on the selected video output, and
        if no support is available, this will act like ``video``.
    <each-frame>
        Take a screenshot each frame. Issue this command again to stop taking
        screenshots. Note that you should disable frame-dropping when using
        this mode - or you might receive duplicate images in cases when a
        frame was dropped. This flag can be combined with the other flags,
        e.g. ``video+each-frame``.

    Older mpv versions required passing ``single`` and ``each-frame`` as
    second argument (and did not have flags). This syntax is still understood,
    but deprecated and might be removed in the future.

    Setting the ``async`` flag will make encoding and writing the actual image
    file asynchronous in most cases. (``each-frame`` mode ignores this flag
    currently.) Requesting async screenshots too early or too often could lead
    to the same filenames being chosen, and overwriting each others in undefined
    order.

``screenshot-to-file "<filename>" [subtitles|video|window]``
    Take a screenshot and save it to a given file. The format of the file will
    be guessed by the extension (and ``--screenshot-format`` is ignored - the
    behavior when the extension is missing or unknown is arbitrary).

    The second argument is like the first argument to ``screenshot``.

    If the file already exists, it's overwritten.

    Like all input command parameters, the filename is subject to property
    expansion as described in `Property Expansion`_.

    The ``async`` flag has an effect on this command (see ``screenshot``
    command).

``playlist-next [weak|force]``
    Go to the next entry on the playlist.

    weak (default)
        If the last file on the playlist is currently played, do nothing.
    force
        Terminate playback if there are no more files on the playlist.

``playlist-prev [weak|force]``
    Go to the previous entry on the playlist.

    weak (default)
        If the first file on the playlist is currently played, do nothing.
    force
        Terminate playback if the first file is being played.

``loadfile "<file>" [replace|append|append-play [options]]``
    Load the given file and play it.

    Second argument:

    <replace> (default)
        Stop playback of the current file, and play the new file immediately.
    <append>
        Append the file to the playlist.
    <append-play>
        Append the file, and if nothing is currently playing, start playback.
        (Always starts with the added file, even if the playlist was not empty
        before running this command.)

    The third argument is a list of options and values which should be set
    while the file is playing. It is of the form ``opt1=value1,opt2=value2,..``.
    Not all options can be changed this way. Some options require a restart
    of the player.

``loadlist "<playlist>" [replace|append]``
    Load the given playlist file (like ``--playlist``).

``playlist-clear``
    Clear the playlist, except the currently played file.

``playlist-remove current|<index>``
    Remove the playlist entry at the given index. Index values start counting
    with 0. The special value ``current`` removes the current entry. Note that
    removing the current entry also stops playback and starts playing the next
    entry.

``playlist-move <index1> <index2>``
    Move the playlist entry at index1, so that it takes the place of the
    entry index2. (Paradoxically, the moved playlist entry will not have
    the index value index2 after moving if index1 was lower than index2,
    because index2 refers to the target entry, not the index the entry
    will have after moving.)

``playlist-shuffle``
    Shuffle the playlist. This is similar to what is done on start if the
    ``--shuffle`` option is used.

``run "command" "arg1" "arg2" ...``
    Run the given command. Unlike in MPlayer/mplayer2 and earlier versions of
    mpv (0.2.x and older), this doesn't call the shell. Instead, the command
    is run directly, with each argument passed separately. Each argument is
    expanded like in `Property Expansion`_. Note that there is a static limit
    of (as of this writing) 9 arguments (this limit could be raised on demand).

    The program is run in a detached way. mpv doesn't wait until the command
    is completed, but continues playback right after spawning it.

    To get the old behavior, use ``/bin/sh`` and ``-c`` as the first two
    arguments.

    .. admonition:: Example

        ``run "/bin/sh" "-c" "echo ${title} > /tmp/playing"``

        This is not a particularly good example, because it doesn't handle
        escaping, and a specially prepared file might allow an attacker to
        execute arbitrary shell commands. It is recommended to write a small
        shell script, and call that with ``run``.

``quit [<code>]``
    Exit the player. If an argument is given, it's used as process exit code.

``quit-watch-later [<code>]``
    Exit player, and store current playback position. Playing that file later
    will seek to the previous position on start. The (optional) argument is
    exactly as in the ``quit`` command.

``sub-add "<file>" [<flags> [<title> [<lang>]]]``
    Load the given subtitle file. It is selected as current subtitle after
    loading.

    The ``flags`` args is one of the following values:

    <select>

        Select the subtitle immediately.

    <auto>

        Don't select the subtitle. (Or in some special situations, let the
        default stream selection mechanism decide.)

    <cached>

        Select the subtitle. If a subtitle with the same filename was already
        added, that one is selected, instead of loading a duplicate entry.
        (In this case, title/language are ignored, and if the was changed since
        it was loaded, these changes won't be reflected.)

    The ``title`` argument sets the track title in the UI.

    The ``lang`` argument sets the track language, and can also influence
    stream selection with ``flags`` set to ``auto``.

``sub-remove [<id>]``
    Remove the given subtitle track. If the ``id`` argument is missing, remove
    the current track. (Works on external subtitle files only.)

``sub-reload [<id>]``
    Reload the given subtitle tracks. If the ``id`` argument is missing, reload
    the current track. (Works on external subtitle files only.)

    This works by unloading and re-adding the subtitle track.

``sub-step <skip>``
    Change subtitle timing such, that the subtitle event after the next
    ``<skip>`` subtitle events is displayed. ``<skip>`` can be negative to step
    backwards.

``sub-seek <skip>``
    Seek to the next (skip set to 1) or the previous (skip set to -1) subtitle.
    This is similar to ``sub-step``, except that it seeks video and audio
    instead of adjusting the subtitle delay.

    For embedded subtitles (like with Matroska), this works only with subtitle
    events that have already been displayed, or are within a short prefetch
    range.

``print-text "<string>"``
    Print text to stdout. The string can contain properties (see
    `Property Expansion`_).

``show-text "<string>" [<duration>|- [<level>]]``
    Show text on the OSD. The string can contain properties, which are expanded
    as described in `Property Expansion`_. This can be used to show playback
    time, filename, and so on.

    <duration>
        The time in ms to show the message for. By default, it uses the same
        value as ``--osd-duration``.

    <level>
        The minimum OSD level to show the text at (see ``--osd-level``).

``expand-text "<string>"``
    Property-expand the argument and return the expanded string. This can be
    used only through the client API or from a script using
    ``mp.command_native``. (see `Property Expansion`_).

``show-progress``
    Show the progress bar, the elapsed time and the total duration of the file
    on the OSD.

``write-watch-later-config``
    Write the resume config file that the ``quit-watch-later`` command writes,
    but continue playback normally.

``stop``
    Stop playback and clear playlist. With default settings, this is
    essentially like ``quit``. Useful for the client API: playback can be
    stopped without terminating the player.

``mouse <x> <y> [<button> [single|double]]``
    Send a mouse event with given coordinate (``<x>``, ``<y>``).

    Second argument:

    <button>
        The button number of clicked mouse button. This should be one of 0-19.
        If ``<button>`` is omitted, only the position will be updated.

    Third argument:

    <single> (default)
        The mouse event represents regular single click.

    <double>
        The mouse event represents double-click.

``keypress <key_name>``
    Send a key event through mpv's input handler, triggering whatever
    behavior is configured to that key. ``key_name`` uses the ``input.conf``
    naming scheme for keys and modifiers. Useful for the client API: key events
    can be sent to libmpv to handle internally.

``keydown <key_name>``
    Similar to ``keypress``, but sets the ``KEYDOWN`` flag so that if the key is
    bound to a repeatable command, it will be run repeatedly with mpv's key
    repeat timing until the ``keyup`` command is called.

``keyup [<key_name>]``
    Set the ``KEYUP`` flag, stopping any repeated behavior that had been
    triggered. ``key_name`` is optional. If ``key_name`` is not given or is an
    empty string, ``KEYUP`` will be set on all keys. Otherwise, ``KEYUP`` will
    only be set on the key specified by ``key_name``.

``audio-add "<file>" [<flags> [<title> [<lang>]]]``
    Load the given audio file. See ``sub-add`` command.

``audio-remove [<id>]``
    Remove the given audio track. See ``sub-remove`` command.

``audio-reload [<id>]``
    Reload the given audio tracks. See ``sub-reload`` command.

``rescan-external-files [<mode>]``
    Rescan external files according to the current ``--sub-auto`` and
    ``--audio-file-auto`` settings. This can be used to auto-load external
    files *after* the file was loaded.

    The ``mode`` argument is one of the following:

    <reselect> (default)
        Select the default audio and subtitle streams, which typically selects
        external files with the highest preference. (The implementation is not
        perfect, and could be improved on request.)

    <keep-selection>
        Do not change current track selections.


Input Commands that are Possibly Subject to Change
--------------------------------------------------

``af set|add|toggle|del|clr "filter1=params,filter2,..."``
    Change audio filter chain. See ``vf`` command.

``vf set|add|toggle|del|clr "filter1=params,filter2,..."``
    Change video filter chain.

    The first argument decides what happens:

    set
        Overwrite the previous filter chain with the new one.

    add
        Append the new filter chain to the previous one.

    toggle
        Check if the given filter (with the exact parameters) is already
        in the video chain. If yes, remove the filter. If no, add the filter.
        (If several filters are passed to the command, this is done for
        each filter.)

        A special variant is combining this with labels, and using ``@name``
        without filter name and parameters as filter entry. This toggles the
        enable/disable flag.

    del
        Remove the given filters from the video chain. Unlike in the other
        cases, the second parameter is a comma separated list of filter names
        or integer indexes. ``0`` would denote the first filter. Negative
        indexes start from the last filter, and ``-1`` denotes the last
        filter.

    clr
        Remove all filters. Note that like the other sub-commands, this does
        not control automatically inserted filters.

    The argument is always needed. E.g. in case of ``clr`` use ``vf clr ""``.

    You can assign labels to filter by prefixing them with ``@name:`` (where
    ``name`` is a user-chosen arbitrary identifier). Labels can be used to
    refer to filters by name in all of the filter chain modification commands.
    For ``add``, using an already used label will replace the existing filter.

    The ``vf`` command shows the list of requested filters on the OSD after
    changing the filter chain. This is roughly equivalent to
    ``show-text ${vf}``. Note that auto-inserted filters for format conversion
    are not shown on the list, only what was requested by the user.

    Normally, the commands will check whether the video chain is recreated
    successfully, and will undo the operation on failure. If the command is run
    before video is configured (can happen if the command is run immediately
    after opening a file and before a video frame is decoded), this check can't
    be run. Then it can happen that creating the video chain fails.

    .. admonition:: Example for input.conf

        - ``a vf set flip`` turn video upside-down on the ``a`` key
        - ``b vf set ""`` remove all video filters on ``b``
        - ``c vf toggle lavfi=gradfun`` toggle debanding on ``c``

    .. admonition:: Example how to toggle disabled filters at runtime

        - Add something ``vf-add=@deband:!lavfi=[gradfun]`` to ``mpv.conf``. The
          ``@deband:`` is the label, and ``deband`` is an arbitrary, user-given
          name for this filter entry. The ``!`` before the filter name disables
          the filter by default. Everything after this is the normal filter name
          and the filter parameters.
        - Add ``a vf toggle @deband`` to ``input.conf``. This toggles the
          "disabled" flag for the filter identified with ``deband``.

``cycle-values ["!reverse"] <property> "<value1>" "<value2>" ...``
    Cycle through a list of values. Each invocation of the command will set the
    given property to the next value in the list. The command maintains an
    internal counter which value to pick next, and which is initially 0. It is
    reset to 0 once the last value is reached.

    The internal counter is associated using the property name and the value
    list. If multiple commands (bound to different keys) use the same name
    and value list, they will share the internal counter.

    The special argument ``!reverse`` can be used to cycle the value list in
    reverse. Compared with a command that just lists the value in reverse, this
    command will actually share the internal counter with the forward-cycling
    key binding (as long as the rest of the arguments are the same).

    Note that there is a static limit of (as of this writing) 10 arguments
    (this limit could be raised on demand).

``enable-section "<section>" [flags]``
    Enable all key bindings in the named input section.

    The enabled input sections form a stack. Bindings in sections on the top of
    the stack are preferred to lower sections. This command puts the section
    on top of the stack. If the section was already on the stack, it is
    implicitly removed beforehand. (A section cannot be on the stack more than
    once.)

    The ``flags`` parameter can be a combination (separated by ``+``) of the
    following flags:

    <exclusive>
        All sections enabled before the newly enabled section are disabled.
        They will be re-enabled as soon as all exclusive sections above them
        are removed. In other words, the new section shadows all previous
        sections.
    <allow-hide-cursor>
        This feature can't be used through the public API.
    <allow-vo-dragging>
        Same.

``disable-section "<section>"``
    Disable the named input section. Undoes ``enable-section``.

``define-section "<section>" "<contents>" [default|force]``
    Create a named input section, or replace the contents of an already existing
    input section. The ``contents`` parameter uses the same syntax as the
    ``input.conf`` file (except that using the section syntax in it is not
    allowed), including the need to separate bindings with a newline character.

    If the ``contents`` parameter is an empty string, the section is removed.

    The section with the name ``default`` is the normal input section.

    In general, input sections have to be enabled with the ``enable-section``
    command, or they are ignored.

    The last parameter has the following meaning:

    <default> (also used if parameter omitted)
        Use a key binding defined by this section only if the user hasn't
        already bound this key to a command.
    <force>
        Always bind a key. (The input section that was made active most recently
        wins if there are ambiguities.)

    This command can be used to dispatch arbitrary keys to a script or a client
    API user. If the input section defines ``script-binding`` commands, it is
    also possible to get separate events on key up/down, and relatively detailed
    information about the key state. The special key name ``unmapped`` can be
    used to match any unmapped key.

``overlay-add <id> <x> <y> "<file>" <offset> "<fmt>" <w> <h> <stride>``
    Add an OSD overlay sourced from raw data. This might be useful for scripts
    and applications controlling mpv, and which want to display things on top
    of the video window.

    Overlays are usually displayed in screen resolution, but with some VOs,
    the resolution is reduced to that of the video's. You can read the
    ``osd-width`` and ``osd-height`` properties. At least with ``--vo-xv`` and
    anamorphic video (such as DVD), ``osd-par`` should be read as well, and the
    overlay should be aspect-compensated.

    ``id`` is an integer between 0 and 63 identifying the overlay element. The
    ID can be used to add multiple overlay parts, update a part by using this
    command with an already existing ID, or to remove a part with
    ``overlay-remove``. Using a previously unused ID will add a new overlay,
    while reusing an ID will update it.

    ``x`` and ``y`` specify the position where the OSD should be displayed.

    ``file`` specifies the file the raw image data is read from. It can be
    either a numeric UNIX file descriptor prefixed with ``@`` (e.g. ``@4``),
    or a filename. The file will be mapped into memory with ``mmap()``,
    copied, and unmapped before the command returns (changed in mpv 0.18.1).

    It is also possible to pass a raw memory address for use as bitmap memory
    by passing a memory address as integer prefixed with an ``&`` character.
    Passing the wrong thing here will crash the player. This mode might be
    useful for use with libmpv. The ``offset`` parameter is simply added to the
    memory address (since mpv 0.8.0, ignored before).

    ``offset`` is the byte offset of the first pixel in the source file.
    (The current implementation always mmap's the whole file from position 0 to
    the end of the image, so large offsets should be avoided. Before mpv 0.8.0,
    the offset was actually passed directly to ``mmap``, but it was changed to
    make using it easier.)

    ``fmt`` is a string identifying the image format. Currently, only ``bgra``
    is defined. This format has 4 bytes per pixels, with 8 bits per component.
    The least significant 8 bits are blue, and the most significant 8 bits
    are alpha (in little endian, the components are B-G-R-A, with B as first
    byte). This uses premultiplied alpha: every color component is already
    multiplied with the alpha component. This means the numeric value of each
    component is equal to or smaller than the alpha component. (Violating this
    rule will lead to different results with different VOs: numeric overflows
    resulting from blending broken alpha values is considered something that
    shouldn't happen, and consequently implementations don't ensure that you
    get predictable behavior in this case.)

    ``w``, ``h``, and ``stride`` specify the size of the overlay. ``w`` is the
    visible width of the overlay, while ``stride`` gives the width in bytes in
    memory. In the simple case, and with the ``bgra`` format, ``stride==4*w``.
    In general, the total amount of memory accessed is ``stride * h``.
    (Technically, the minimum size would be ``stride * (h - 1) + w * 4``, but
    for simplicity, the player will access all ``stride * h`` bytes.)

    .. note::

        Before mpv 0.18.1, you had to do manual "double buffering" when updating
        an overlay by replacing it with a different memory buffer. Since mpv
        0.18.1, the memory is simply copied and doesn't reference any of the
        memory indicated by the command's arguments after the commend returns.
        If you want to use this command before mpv 0.18.1, reads the old docs
        to see how to handle this correctly.

``overlay-remove <id>``
    Remove an overlay added with ``overlay-add`` and the same ID. Does nothing
    if no overlay with this ID exists.

``script-message "<arg1>" "<arg2>" ...``
    Send a message to all clients, and pass it the following list of arguments.
    What this message means, how many arguments it takes, and what the arguments
    mean is fully up to the receiver and the sender. Every client receives the
    message, so be careful about name clashes (or use ``script-message-to``).

``script-message-to "<target>" "<arg1>" "<arg2>" ...``
    Same as ``script-message``, but send it only to the client named
    ``<target>``. Each client (scripts etc.) has a unique name. For example,
    Lua scripts can get their name via ``mp.get_script_name()``.

``script-binding "<name>"``
    Invoke a script-provided key binding. This can be used to remap key
    bindings provided by external Lua scripts.

    The argument is the name of the binding.

    It can optionally be prefixed with the name of the script, using ``/`` as
    separator, e.g. ``script-binding scriptname/bindingname``.

    For completeness, here is how this command works internally. The details
    could change any time. On any matching key event, ``script-message-to``
    or ``script-message`` is called (depending on whether the script name is
    included), with the following arguments:

    1. The string ``key-binding``.
    2. The name of the binding (as established above).
    3. The key state as string (see below).
    4. The key name (since mpv 0.15.0).

    The key state consists of 2 letters:

    1. One of ``d`` (key was pressed down), ``u`` (was released), ``r`` (key
       is still down, and was repeated; only if key repeat is enabled for this
       binding), ``p`` (key was pressed; happens if up/down can't be tracked).
    2. Whether the event originates from the mouse, either ``m`` (mouse button)
       or ``-`` (something else).

``ab-loop``
    Cycle through A-B loop states. The first command will set the ``A`` point
    (the ``ab-loop-a`` property); the second the ``B`` point, and the third
    will clear both points.

``drop-buffers``
    Drop audio/video/demuxer buffers, and restart from fresh. Might help with
    unseekable streams that are going out of sync.
    This command might be changed or removed in the future.

``screenshot-raw [subtitles|video|window]``
    Return a screenshot in memory. This can be used only through the client
    API. The MPV_FORMAT_NODE_MAP returned by this command has the ``w``, ``h``,
    ``stride`` fields set to obvious contents. The ``format`` field is set to
    ``bgr0`` by default. This format is organized as ``B8G8R8X8`` (where ``B``
    is the LSB). The contents of the padding ``X`` are undefined. The ``data``
    field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image
    is freed as soon as the result mpv_node is freed. As usual with client API
    semantics, you are not allowed to write to the image data.

``vf-command "<label>" "<cmd>" "<args>"``
    Send a command to the filter with the given ``<label>``. Use ``all`` to send
    it to all filters at once. The command and argument string is filter
    specific. Currently, this only works with the ``lavfi`` filter - see
    the libavfilter documentation for which commands a filter supports.

    Note that the ``<label>`` is a mpv filter label, not a libavfilter filter
    name.

``af-command "<label>" "<cmd>" "<args>"``
    Same as ``vf-command``, but for audio filters.

``apply-profile "<name>"``
    Apply the contents of a named profile. This is like using ``profile=name``
    in a config file, except you can map it to a key binding to change it at
    runtime.

    There is no such thing as "unapplying" a profile - applying a profile
    merely sets all option values listed within the profile.

``load-script "<path>"``
    Load a script, similar to the ``--script`` option.

Undocumented commands: ``tv-last-channel`` (TV/DVB only),
``ao-reload`` (experimental/internal).

Hooks
~~~~~

Hooks are synchronous events between player core and a script or similar. This
applies to client API (including the Lua scripting interface). Normally,
events are supposed to be asynchronous, and the hook API provides an awkward
and obscure way to handle events that require stricter coordination. There are
no API stability guarantees made. Not following the protocol exactly can make
the player freeze randomly. Basically, nobody should use this API.

There are two special commands involved. Also, the client must listen for
client messages (``MPV_EVENT_CLIENT_MESSAGE`` in the C API).

``hook-add <hook-name> <id> <priority>``
    Subscribe to the hook identified by the first argument (basically, the
    name of event). The ``id`` argument is an arbitrary integer chosen by the
    user. ``priority`` is used to sort all hook handlers globally across all
    clients. Each client can register multiple hook handlers (even for the
    same hook-name). Once the hook is registered, it cannot be unregistered.

    When a specific event happens, all registered handlers are run serially.
    This uses a protocol every client has to follow explicitly. When a hook
    handler is run, a client message (``MPV_EVENT_CLIENT_MESSAGE``) is sent to
    the client which registered the hook. This message has the following
    arguments:

    1. the string ``hook_run``
    2. the ``id`` argument the hook was registered with as string (this can be
       used to correctly handle multiple hooks registered by the same client,
       as long as the ``id`` argument is unique in the client)
    3. something undefined, used by the hook mechanism to track hook execution
       (currently, it's the hook-name, but this might change without warning)

    Upon receiving this message, the client can handle the event. While doing
    this, the player core will still react to requests, but playback will
    typically be stopped.

    When the client is done, it must continue the core's hook execution by
    running the ``hook-ack`` command.

``hook-ack <string>``
    Run the next hook in the global chain of hooks. The argument is the 3rd
    argument of the client message that starts hook execution for the
    current client.

The following hooks are currently defined:

``on_load``
    Called when a file is to be opened, before anything is actually done.
    For example, you could read and write the ``stream-open-filename``
    property to redirect an URL to something else (consider support for
    streaming sites which rarely give the user a direct media URL), or
    you could set per-file options with by setting the property
    ``file-local-options/<option name>``. The player will wait until all
    hooks are run.

``on_preloaded``
    Called after a file has been opened, and before tracks are selected and
    decoders are created. This has some usefulness if an API users wants
    to select tracks manually, based on the set of available tracks. It's
    also useful to initialize ``--lavfi-complex`` in a specific way by API,
    without having to "probe" the available streams at first.

    Note that this does not yet apply default track selection. Which operations
    exactly can be done and not be done, and what information is available and
    what is not yet available yet, is all subject to change.

``on_unload``
    Run before closing a file, and before actually uninitializing
    everything. It's not possible to resume playback in this state.

Input Command Prefixes
----------------------

These prefixes are placed between key name and the actual command. Multiple
prefixes can be specified. They are separated by whitespace.

``osd-auto``
    Use the default behavior for this command. This is the default for
    ``input.conf`` commands. Some libmpv/scripting/IPC APIs do not use this as
    default, but use ``no-osd`` instead.
``no-osd``
    Do not use any OSD for this command.
``osd-bar``
    If possible, show a bar with this command. Seek commands will show the
    progress bar, property changing commands may show the newly set value.
``osd-msg``
    If possible, show an OSD message with this command. Seek command show
    the current playback time, property changing commands show the newly set
    value as text.
``osd-msg-bar``
    Combine osd-bar and osd-msg.
``raw``
    Do not expand properties in string arguments. (Like ``"${property-name}"``.)
    This is the default for some libmpv/scripting/IPC APIs.
``expand-properties``
    All string arguments are expanded as described in `Property Expansion`_.
    This is the default for ``input.conf`` commands.
``repeatable``
    For some commands, keeping a key pressed doesn't run the command repeatedly.
    This prefix forces enabling key repeat in any case.
``async``
    Allow asynchronous execution (if possible). Note that only a few commands
    will support this (usually this is explicitly documented). Some commands
    are asynchronous by default (or rather, their effects might manifest
    after completion of the command). The semantics of this flag might change
    in the future. Set it only if you don't rely on the effects of this command
    being fully realized when it returns.

All of the osd prefixes are still overridden by the global ``--osd-level``
settings.

Input Sections
--------------

Input sections group a set of bindings, and enable or disable them at once.
In ``input.conf``, each key binding is assigned to an input section, rather
than actually having explicit text sections.

See also: ``enable-section`` and ``disable-section`` commands.

Predefined bindings:

``default``
    Bindings without input section are implicitly assigned to this section. It
    is enabled by default during normal playback.
``encode``
    Section which is active in encoding mode. It is enabled exclusively, so
    that bindings in the ``default`` sections are ignored.

Properties
----------

Properties are used to set mpv options during runtime, or to query arbitrary
information. They can be manipulated with the ``set``/``add``/``cycle``
commands, and retrieved with ``show-text``, or anything else that uses property
expansion. (See `Property Expansion`_.)

The property name is annotated with RW to indicate whether the property is
generally writable.

If an option is referenced, the property will normally take/return exactly the
same values as the option. In these cases, properties are merely a way to change
an option at runtime.

Property list
-------------

.. note::

    Most options can be set as runtime via properties as well. Just remove the
    leading ``--`` from the option name. These are not documented. Only
    properties which do not exist as option with the same name, or which have
    very different behavior from the options are documented below.

``audio-speed-correction``, ``video-speed-correction``
    Factor multiplied with ``speed`` at which the player attempts to play the
    file. Usually it's exactly 1. (Display sync mode will make this useful.)

    OSD formatting will display it in the form of ``+1.23456%``, with the number
    being ``(raw - 1) * 100`` for the given raw property value.

``display-sync-active``
    Return whether ``--video-sync=display`` is actually active.

``filename``
    Currently played file, with path stripped. If this is an URL, try to undo
    percent encoding as well. (The result is not necessarily correct, but
    looks better for display purposes. Use the ``path`` property to get an
    unmodified filename.)

    This has a sub-property:

    ``filename/no-ext``
        Like the ``filename`` property, but if the text contains a ``.``, strip
        all text after the last ``.``. Usually this removes the file extension.

``file-size``
    Length in bytes of the source file/stream. (This is the same as
    ``${stream-end}``. For segmented/multi-part files, this will return the
    size of the main or manifest file, whatever it is.)

``estimated-frame-count``
    Total number of frames in current file.

    .. note:: This is only an estimate. (It's computed from two unreliable
              quantities: fps and stream length.)

``estimated-frame-number``
    Number of current frame in current stream.

    .. note:: This is only an estimate. (It's computed from two unreliable
              quantities: fps and possibly rounded timestamps.)

``path``
    Full path of the currently played file. Usually this is exactly the same
    string you pass on the mpv command line or the ``loadfile`` command, even
    if it's a relative path. If you expect an absolute path, you will have to
    determine it yourself, for example by using the ``working-directory``
    property.

``media-title``
    If the currently played file has a ``title`` tag, use that.

    Otherwise, if the media type is DVD, return the volume ID of DVD.

    Otherwise, return the ``filename`` property.

``file-format``
    Symbolic name of the file format. In some cases, this is a comma-separated
    list of format names, e.g. mp4 is ``mov,mp4,m4a,3gp,3g2,mj2`` (the list
    may grow in the future for any format).

``current-demuxer``
    Name of the current demuxer. (This is useless.)

    (Renamed from ``demuxer``.)

``stream-path``
    Filename (full path) of the stream layer filename. (This is probably
    useless and is almost never different from ``path``.)

``stream-pos``
    Raw byte position in source stream. Technically, this returns the position
    of the most recent packet passed to a decoder.

``stream-end``
    Raw end position in bytes in source stream.

``duration``
    Duration of the current file in seconds. If the duration is unknown, the
    property is unavailable. Note that the file duration is not always exactly
    known, so this is an estimate.

    This replaces the ``length`` property, which was deprecated after the
    mpv 0.9 release. (The semantics are the same.)

``avsync``
    Last A/V synchronization difference. Unavailable if audio or video is
    disabled.

``total-avsync-change``
    Total A-V sync correction done. Unavailable if audio or video is
    disabled.

``decoder-frame-drop-count``
    Video frames dropped by decoder, because video is too far behind audio (when
    using ``--framedrop=decoder``). Sometimes, this may be incremented in other
    situations, e.g. when video packets are damaged, or the decoder doesn't
    follow the usual rules. Unavailable if video is disabled.

    ``drop-frame-count`` is a deprecated alias.

``frame-drop-count``
    Frames dropped by VO (when using ``--framedrop=vo``).

    ``vo-drop-frame-count`` is a deprecated alias.

``mistimed-frame-count``
    Number of video frames that were not timed correctly in display-sync mode
    for the sake of keeping A/V sync. This does not include external
    circumstances, such as video rendering being too slow or the graphics
    driver somehow skipping a vsync. It does not include rounding errors either
    (which can happen especially with bad source timestamps). For example,
    using the ``display-desync`` mode should never change this value from 0.

``vsync-ratio``
    For how many vsyncs a frame is displayed on average. This is available if
    display-sync is active only. For 30 FPS video on a 60 Hz screen, this will
    be 2. This is the moving average of what actually has been scheduled, so
    24 FPS on 60 Hz will never remain exactly on 2.5, but jitter depending on
    the last frame displayed.

``vo-delayed-frame-count``
    Estimated number of frames delayed due to external circumstances in
    display-sync mode. Note that in general, mpv has to guess that this is
    happening, and the guess can be inaccurate.

``percent-pos`` (RW)
    Position in current file (0-100). The advantage over using this instead of
    calculating it out of other properties is that it properly falls back to
    estimating the playback position from the byte position, if the file
    duration is not known.

``time-pos`` (RW)
    Position in current file in seconds.

``time-start``
    Deprecated. Always returns 0. Before mpv 0.14, this used to return the start
    time of the file (could affect e.g. transport streams). See
    ``--rebase-start-time`` option.

``time-remaining``
    Remaining length of the file in seconds. Note that the file duration is not
    always exactly known, so this is an estimate.

``audio-pts`` (R)
    Current audio playback position in current file in seconds. Unlike time-pos,
    this updates more often than once per frame. For audio-only files, it is
    mostly equivalent to time-pos, while for video-only files this property is
    not available.

``playtime-remaining``
    ``time-remaining`` scaled by the current ``speed``.

``playback-time`` (RW)
    Position in current file in seconds. Unlike ``time-pos``, the time is
    clamped to the range of the file. (Inaccurate file durations etc. could
    make it go out of range. Useful on attempts to seek outside of the file,
    as the seek target time is considered the current position during seeking.)

``chapter`` (RW)
    Current chapter number. The number of the first chapter is 0.

``edition`` (RW)
    Current MKV edition number. Setting this property to a different value will
    restart playback. The number of the first edition is 0.

``disc-titles``
    Number of BD/DVD titles.

    This has a number of sub-properties. Replace ``N`` with the 0-based edition
    index.

    ``disc-titles/count``
        Number of titles.

    ``disc-titles/id``
        Title ID as integer. Currently, this is the same as the title index.

    ``disc-titles/length``
        Length in seconds. Can be unavailable in a number of cases (currently
        it works for libdvdnav only).

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP (for each edition)
                "id"                MPV_FORMAT_INT64
                "length"            MPV_FORMAT_DOUBLE

``disc-title-list``
    List of BD/DVD titles.

``disc-title`` (RW)
    Current BD/DVD title number. Writing works only for ``dvdnav://`` and
    ``bd://`` (and aliases for these).

``chapters``
    Number of chapters.

``editions``
    Number of MKV editions.

``edition-list``
    List of editions, current entry marked. Currently, the raw property value
    is useless.

    This has a number of sub-properties. Replace ``N`` with the 0-based edition
    index.

    ``edition-list/count``
        Number of editions. If there are no editions, this can be 0 or 1 (1
        if there's a useless dummy edition).

    ``edition-list/N/id``
        Edition ID as integer. Use this to set the ``edition`` property.
        Currently, this is the same as the edition index.

    ``edition-list/N/default``
        ``yes`` if this is the default edition, ``no`` otherwise.

    ``edition-list/N/title``
        Edition title as stored in the file. Not always available.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP (for each edition)
                "id"                MPV_FORMAT_INT64
                "title"             MPV_FORMAT_STRING
                "default"           MPV_FORMAT_FLAG

``angle`` (RW)
    Current DVD angle.

``metadata``
    Metadata key/value pairs.

    If the property is accessed with Lua's ``mp.get_property_native``, this
    returns a table with metadata keys mapping to metadata values. If it is
    accessed with the client API, this returns a ``MPV_FORMAT_NODE_MAP``,
    with tag keys mapping to tag values.

    For OSD, it returns a formatted list. Trying to retrieve this property as
    a raw string doesn't work.

    This has a number of sub-properties:

    ``metadata/by-key/<key>``
        Value of metadata entry ``<key>``.

    ``metadata/list/count``
        Number of metadata entries.

    ``metadata/list/N/key``
        Key name of the Nth metadata entry. (The first entry is ``0``).

    ``metadata/list/N/value``
        Value of the Nth metadata entry.

    ``metadata/<key>``
        Old version of ``metadata/by-key/<key>``. Use is discouraged, because
        the metadata key string could conflict with other sub-properties.

    The layout of this property might be subject to change. Suggestions are
    welcome how exactly this property should work.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_MAP
            (key and string value for each metadata entry)

``filtered-metadata``
    Like ``metadata``, but includes only fields listed in the ``--display-tags``
    option. This is the same set of tags that is printed to the terminal.

``chapter-metadata``
    Metadata of current chapter. Works similar to ``metadata`` property. It
    also allows the same access methods (using sub-properties).

    Per-chapter metadata is very rare. Usually, only the chapter name
    (``title``) is set.

    For accessing other information, like chapter start, see the
    ``chapter-list`` property.

``vf-metadata/<filter-label>``
    Metadata added by video filters. Accessed by the filter label,
    which, if not explicitly specified using the ``@filter-label:`` syntax,
    will be ``<filter-name>NN``.

    Works similar to ``metadata`` property. It allows the same access
    methods (using sub-properties).

    An example of this kind of metadata are the cropping parameters
    added by ``--vf=lavfi=cropdetect``.

``af-metadata/<filter-label>``
    Equivalent to ``vf-metadata/<filter-label>``, but for audio filters.

``idle-active``
    Return ``yes`` if no file is loaded, but the player is staying around
    because of the ``--idle`` option.

    (Renamed from ``idle``.)

``core-idle``
    Return ``yes`` if the playback core is paused, otherwise ``no``. This can
    be different ``pause`` in special situations, such as when the player
    pauses itself due to low network cache.

    This also returns ``yes`` if playback is restarting or if nothing is
    playing at all. In other words, it's only ``no`` if there's actually
    video playing. (Behavior since mpv 0.7.0.)

``cache``
    Network cache fill state (0-100.0).

``cache-size`` (RW)
    Network cache size in KB. This is similar to ``--cache``. This allows
    setting the cache size at runtime. Currently, it's not possible to enable
    or disable the cache at runtime using this property, just to resize an
    existing cache.

    This does not include the backbuffer size (changed after mpv 0.10.0).

    Note that this tries to keep the cache contents as far as possible. To make
    this easier, the cache resizing code will allocate the new cache while the
    old cache is still allocated.

    Don't use this when playing DVD or Blu-ray.

``cache-free`` (R)
    Total free cache size in KB.

``cache-used`` (R)
    Total used cache size in KB.

``cache-speed`` (R)
    Current I/O read speed between the cache and the lower layer (like network).
    This gives the number bytes per seconds over a 1 second window (using
    the type ``MPV_FORMAT_INT64`` for the client API).

``cache-idle`` (R)
    Returns ``yes`` if the cache is idle, which means the cache is filled as
    much as possible, and is currently not reading more data.

``demuxer-cache-duration``
    Approximate duration of video buffered in the demuxer, in seconds. The
    guess is very unreliable, and often the property will not be available
    at all, even if data is buffered.

``demuxer-cache-time``
    Approximate time of video buffered in the demuxer, in seconds. Same as
    ``demuxer-cache-duration`` but returns the last timestamp of buffered
    data in demuxer.

``demuxer-cache-idle``
    Returns ``yes`` if the demuxer is idle, which means the demuxer cache is
    filled to the requested amount, and is currently not reading more data.

``demuxer-cache-state``
    Various undocumented or half-documented things.

    Each entry in ``seekable-ranges`` represents a region in the demuxer cache
    that can be seeked to. If there are multiple demuxers active, this only
    returns information about the "main" demuxer, but might be changed in
    future to return unified information about all demuxers. The ranges are in
    arbitrary order. Often, ranges will overlap for a bit, before being joined.
    In broken corner cases, ranges may overlap all over the place.

    The end of a seek range is usually smaller than the value returned by the
    ``demuxer-cache-time`` property, because that property returns the guessed
    buffering amount, while the seek ranges represent the buffered data that
    can actually be used for cached seeking.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_MAP
            "seekable-ranges"   MPV_FORMAT_NODE_ARRAY
                MPV_FORMAT_NODE_MAP
                    "start"             MPV_FORMAT_DOUBLE
                    "end"               MPV_FORMAT_DOUBLE

``demuxer-via-network``
    Returns ``yes`` if the stream demuxed via the main demuxer is most likely
    played via network. What constitutes "network" is not always clear, might
    be used for other types of untrusted streams, could be wrong in certain
    cases, and its definition might be changing. Also, external files (like
    separate audio files or streams) do not influence the value of this
    property (currently).

``demuxer-start-time`` (R)
    Returns the start time reported by the demuxer in fractional seconds.

``paused-for-cache``
    Returns ``yes`` when playback is paused because of waiting for the cache.

``cache-buffering-state``
    Return the percentage (0-100) of the cache fill status until the player
    will unpause (related to ``paused-for-cache``).

``eof-reached``
    Returns ``yes`` if end of playback was reached, ``no`` otherwise. Note
    that this is usually interesting only if ``--keep-open`` is enabled,
    since otherwise the player will immediately play the next file (or exit
    or enter idle mode), and in these cases the ``eof-reached`` property will
    logically be cleared immediately after it's set.

``seeking``
    Returns ``yes`` if the player is currently seeking, or otherwise trying
    to restart playback. (It's possible that it returns ``yes`` while a file
    is loadedThis is because the same underlying code is used for seeking and
    resyncing.)

``mixer-active``
    Return ``yes`` if the audio mixer is active, ``no`` otherwise.

    This option is relatively useless. Before mpv 0.18.1, it could be used to
    infer behavior of the ``volume`` property.

``ao-volume`` (RW)
    System volume. This property is available only if mpv audio output is
    currently active, and only if the underlying implementation supports volume
    control. What this option does depends on the API. For example, on ALSA
    this usually changes system-wide audio, while with PulseAudio this controls
    per-application volume.

``ao-mute`` (RW)
    Similar to ``ao-volume``, but controls the mute state. May be unimplemented
    even if ``ao-volume`` works.

``audio-codec``
    Audio codec selected for decoding.

``audio-codec-name``
    Audio codec.

``audio-params``
    Audio format as output by the audio decoder.
    This has a number of sub-properties:

    ``audio-params/format``
        The sample format as string. This uses the same names as used in other
        places of mpv.

    ``audio-params/samplerate``
        Samplerate.

    ``audio-params/channels``
        The channel layout as a string. This is similar to what the
        ``--audio-channels`` accepts.

    ``audio-params/hr-channels``
        As ``channels``, but instead of the possibly cryptic actual layout
        sent to the audio device, return a hopefully more human readable form.
        (Usually only ``audio-out-params/hr-channels`` makes sense.)

    ``audio-params/channel-count``
        Number of audio channels. This is redundant to the ``channels`` field
        described above.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_MAP
            "format"            MPV_FORMAT_STRING
            "samplerate"        MPV_FORMAT_INT64
            "channels"          MPV_FORMAT_STRING
            "channel-count"     MPV_FORMAT_INT64
            "hr-channels"       MPV_FORMAT_STRING

``audio-out-params``
    Same as ``audio-params``, but the format of the data written to the audio
    API.

``colormatrix`` (R)
    Redirects to ``video-params/colormatrix``. This parameter (as well as
    similar ones) can be overridden with the ``format`` video filter.

``colormatrix-input-range`` (R)
    See ``colormatrix``.

``colormatrix-primaries`` (R)
    See ``colormatrix``.

``hwdec`` (RW)
    Reflects the ``--hwdec`` option.

    Writing to it may change the currently used hardware decoder, if possible.
    (Internally, the player may reinitialize the decoder, and will perform a
    seek to refresh the video properly.) You can watch the other hwdec
    properties to see whether this was successful.

    Unlike in mpv 0.9.x and before, this does not return the currently active
    hardware decoder. Since mpv 0.18.0, ``hwdec-current`` is available for
    this purpose.

``hwdec-current``
    Return the current hardware decoding in use. If decoding is active, return
    one of the values used by the ``hwdec`` option/property. ``no`` indicates
    software decoding. If no decoder is loaded, the property is unavailable.

``hwdec-interop``
    This returns the currently loaded hardware decoding/output interop driver.
    This is known only once the VO has opened (and possibly later). With some
    VOs (like ``opengl``), this might be never known in advance, but only when
    the decoder attempted to create the hw decoder successfully. (Using
    ``--opengl-hwdec-interop`` can load it eagerly.) If there are multiple
    drivers loaded, they will be separated by ``,``.

    If no VO is active or no interop driver is known, this property is
    unavailable.

    This does not necessarily use the same values as ``hwdec``. There can be
    multiple interop drivers for the same hardware decoder, depending on
    platform and VO.

    This is somewhat similar to the ``--opengl-hwdec-interop`` option, but
    it returns the actually loaded backend, not the value of this option.

``video-format``
    Video format as string.

``video-codec``
    Video codec selected for decoding.

``width``, ``height``
    Video size. This uses the size of the video as decoded, or if no video
    frame has been decoded yet, the (possibly incorrect) container indicated
    size.

``video-params``
    Video parameters, as output by the decoder (with overrides like aspect
    etc. applied). This has a number of sub-properties:

    ``video-params/pixelformat``
        The pixel format as string. This uses the same names as used in other
        places of mpv.

    ``video-params/average-bpp``
        Average bits-per-pixel as integer. Subsampled planar formats use a
        different resolution, which is the reason this value can sometimes be
        odd or confusing. Can be unavailable with some formats.

    ``video-params/plane-depth``
        Bit depth for each color component as integer. This is only exposed
        for planar or single-component formats, and is unavailable for other
        formats.

    ``video-params/w``, ``video-params/h``
        Video size as integers, with no aspect correction applied.

    ``video-params/dw``, ``video-params/dh``
        Video size as integers, scaled for correct aspect ratio.

    ``video-params/aspect``
        Display aspect ratio as float.

    ``video-params/par``
        Pixel aspect ratio.

    ``video-params/colormatrix``
        The colormatrix in use as string. (Exact values subject to change.)

    ``video-params/colorlevels``
        The colorlevels as string. (Exact values subject to change.)

    ``video-params/primaries``
        The primaries in use as string. (Exact values subject to change.)

    ``video-params/gamma``
        The gamma function in use as string. (Exact values subject to change.)

    ``video-params/sig-peak``
        The video file's tagged signal peak as float.

    ``video-params/light``
        The light type in use as a string. (Exact values subject to change.)

    ``video-params/chroma-location``
        Chroma location as string. (Exact values subject to change.)

    ``video-params/rotate``
        Intended display rotation in degrees (clockwise).

    ``video-params/stereo-in``
        Source file stereo 3D mode. (See ``--video-stereo-mode`` option.)

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_MAP
            "pixelformat"       MPV_FORMAT_STRING
            "w"                 MPV_FORMAT_INT64
            "h"                 MPV_FORMAT_INT64
            "dw"                MPV_FORMAT_INT64
            "dh"                MPV_FORMAT_INT64
            "aspect"            MPV_FORMAT_DOUBLE
            "par"               MPV_FORMAT_DOUBLE
            "colormatrix"       MPV_FORMAT_STRING
            "colorlevels"       MPV_FORMAT_STRING
            "primaries"         MPV_FORMAT_STRING
            "gamma"             MPV_FORMAT_STRING
            "sig-peak"          MPV_FORMAT_DOUBLE
            "light"             MPV_FORMAT_STRING
            "chroma-location"   MPV_FORMAT_STRING
            "rotate"            MPV_FORMAT_INT64
            "stereo-in"         MPV_FORMAT_STRING

``dwidth``, ``dheight``
    Video display size. This is the video size after filters and aspect scaling
    have been applied. The actual video window size can still be different
    from this, e.g. if the user resized the video window manually.

    These have the same values as ``video-out-params/dw`` and
    ``video-out-params/dh``.

``video-dec-params``
    Exactly like ``video-params``, but no overrides applied.

``video-out-params``
    Same as ``video-params``, but after video filters have been applied. If
    there are no video filters in use, this will contain the same values as
    ``video-params``. Note that this is still not necessarily what the video
    window uses, since the user can change the window size, and all real VOs
    do their own scaling independently from the filter chain.

    Has the same sub-properties as ``video-params``.

``video-frame-info``
    Approximate information of the current frame. Note that if any of these
    are used on OSD, the information might be off by a few frames due to OSD
    redrawing and frame display being somewhat disconnected, and you might
    have to pause and force a redraw.

    Sub-properties:

    ``video-frame-info/picture-type``
    ``video-frame-info/interlaced``
    ``video-frame-info/tff``
    ``video-frame-info/repeat``

``container-fps``
    Container FPS. This can easily contain bogus values. For videos that use
    modern container formats or video codecs, this will often be incorrect.

    (Renamed from ``fps``.)

``estimated-vf-fps``
    Estimated/measured FPS of the video filter chain output. (If no filters
    are used, this corresponds to decoder output.) This uses the average of
    the 10 past frame durations to calculate the FPS. It will be inaccurate
    if frame-dropping is involved (such as when framedrop is explicitly
    enabled, or after precise seeking). Files with imprecise timestamps (such
    as Matroska) might lead to unstable results.

``window-scale`` (RW)
    Window size multiplier. Setting this will resize the video window to the
    values contained in ``dwidth`` and ``dheight`` multiplied with the value
    set with this property. Setting ``1`` will resize to original video size
    (or to be exact, the size the video filters output). ``2`` will set the
    double size, ``0.5`` halves the size.

``window-minimized``
    Return whether the video window is minimized or not.

``display-names``
    Names of the displays that the mpv window covers. On X11, these
    are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Windows, these
    are the GDI names (\\.\DISPLAY1, \\.\DISPLAY2, etc.) and the first display
    in the list will be the one that Windows considers associated with the
    window (as determined by the MonitorFromWindow API.)

``display-fps`` (RW)
    The refresh rate of the current display. Currently, this is the lowest FPS
    of any display covered by the video, as retrieved by the underlying system
    APIs (e.g. xrandr on X11). It is not the measured FPS. It's not necessarily
    available on all platforms. Note that any of the listed facts may change
    any time without a warning.

``estimated-display-fps``
    Only available if display-sync mode (as selected by ``--video-sync``) is
    active. Returns the actual rate at which display refreshes seem to occur,
    measured by system time.

``vsync-jitter``
    Estimated deviation factor of the vsync duration.

``video-aspect`` (RW)
    Video aspect, see ``--video-aspect``.

    If video is active, this reports the effective aspect value, instead of
    the value of the ``--video-aspect`` option.

``osd-width``, ``osd-height``
    Last known OSD width (can be 0). This is needed if you want to use the
    ``overlay-add`` command. It gives you the actual OSD size, which can be
    different from the window size in some cases.

``osd-par``
    Last known OSD display pixel aspect (can be 0).

``program`` (W)
    Switch TS program (write-only).

``dvb-channel`` (W)
    Pair of integers: card,channel of current DVB stream.
    Can be switched to switch to another channel on the same card.

``dvb-channel-name`` (RW)
    Name of current DVB program.
    On write, a channel-switch to the named channel on the same
    card is performed. Can also be used for channel switching.

``sub-text``
    Return the current subtitle text. Formatting is stripped. If a subtitle
    is selected, but no text is currently visible, or the subtitle is not
    text-based (i.e. DVD/BD subtitles), an empty string is returned.

    This property is experimental and might be removed in the future.

``tv-brightness``, ``tv-contrast``, ``tv-saturation``, ``tv-hue`` (RW)
    TV stuff.

``playlist-pos`` (RW)
    Current position on playlist. The first entry is on position 0. Writing
    to the property will restart playback at the written entry.

``playlist-pos-1`` (RW)
    Same as ``playlist-pos``, but 1-based.

``playlist-count``
    Number of total playlist entries.

``playlist``
    Playlist, current entry marked. Currently, the raw property value is
    useless.

    This has a number of sub-properties. Replace ``N`` with the 0-based playlist
    entry index.

    ``playlist/count``
        Number of playlist entries (same as ``playlist-count``).

    ``playlist/N/filename``
        Filename of the Nth entry.

    ``playlist/N/current``, ``playlist/N/playing``
        ``yes`` if this entry is currently playing (or being loaded).
        Unavailable or ``no`` otherwise. When changing files, ``current`` and
        ``playing`` can be different, because the currently playing file hasn't
        been unloaded yet; in this case, ``current`` refers to the new
        selection. (Since mpv 0.7.0.)

    ``playlist/N/title``
        Name of the Nth entry. Only available if the playlist file contains
        such fields, and only if mpv's parser supports it for the given
        playlist format.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP (for each playlist entry)
                "filename"  MPV_FORMAT_STRING
                "current"   MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0)
                "playing"   MPV_FORMAT_FLAG (same)
                "title"     MPV_FORMAT_STRING (optional)

``track-list``
    List of audio/video/sub tracks, current entry marked. Currently, the raw
    property value is useless.

    This has a number of sub-properties. Replace ``N`` with the 0-based track
    index.

    ``track-list/count``
        Total number of tracks.

    ``track-list/N/id``
        The ID as it's used for ``-sid``/``--aid``/``--vid``. This is unique
        within tracks of the same type (sub/audio/video), but otherwise not.

    ``track-list/N/type``
        String describing the media type. One of ``audio``, ``video``, ``sub``.

    ``track-list/N/src-id``
        Track ID as used in the source file. Not always available.

    ``track-list/N/title``
        Track title as it is stored in the file. Not always available.

    ``track-list/N/lang``
        Track language as identified by the file. Not always available.

    ``track-list/N/albumart``
        ``yes`` if this is a video track that consists of a single picture,
        ``no`` or unavailable otherwise. This is used for video tracks that are
        really attached pictures in audio files.

    ``track-list/N/default``
        ``yes`` if the track has the default flag set in the file, ``no``
        otherwise.

    ``track-list/N/forced``
        ``yes`` if the track has the forced flag set in the file, ``no``
        otherwise.

    ``track-list/N/codec``
        The codec name used by this track, for example ``h264``. Unavailable
        in some rare cases.

    ``track-list/N/external``
        ``yes`` if the track is an external file, ``no`` otherwise. This is
        set for separate subtitle files.

    ``track-list/N/external-filename``
        The filename if the track is from an external file, unavailable
        otherwise.

    ``track-list/N/selected``
        ``yes`` if the track is currently decoded, ``no`` otherwise.

    ``track-list/N/ff-index``
        The stream index as usually used by the FFmpeg utilities. Note that
        this can be potentially wrong if a demuxer other than libavformat
        (``--demuxer=lavf``) is used. For mkv files, the index will usually
        match even if the default (builtin) demuxer is used, but there is
        no hard guarantee.

    ``track-list/N/decoder-desc``
        If this track is being decoded, the human-readable decoder name,

    ``track-list/N/demux-w``, ``track-list/N/demux-h``
        Video size hint as indicated by the container. (Not always accurate.)

    ``track-list/N/demux-channel-count``
        Number of audio channels as indicated by the container. (Not always
        accurate - in particular, the track could be decoded as a different
        number of channels.)

    ``track-list/N/demux-channels``
        Channel layout as indicated by the container. (Not always accurate.)

    ``track-list/N/demux-samplerate``
        Audio sample rate as indicated by the container. (Not always accurate.)

    ``track-list/N/demux-fps``
        Video FPS as indicated by the container. (Not always accurate.)

    ``track-list/N/audio-channels`` (deprecated)
        Deprecated alias for ``track-list/N/demux-channel-count``.

    ``track-list/N/replaygain-track-peak``, ``track-list/N/replaygain-track-gain``
        Per-track replaygain values. Only available for audio tracks with
        corresponding information stored in the source file.

    ``track-list/N/replaygain-album-peak``, ``track-list/N/replaygain-album-gain``
        Per-album replaygain values. If the file has per-track but no per-album
        information, the per-album values will be copied from the per-track
        values currently. It's possible that future mpv versions will make
        these properties unavailable instead in this case.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP (for each track)
                "id"                MPV_FORMAT_INT64
                "type"              MPV_FORMAT_STRING
                "src-id"            MPV_FORMAT_INT64
                "title"             MPV_FORMAT_STRING
                "lang"              MPV_FORMAT_STRING
                "albumart"          MPV_FORMAT_FLAG
                "default"           MPV_FORMAT_FLAG
                "forced"            MPV_FORMAT_FLAG
                "selected"          MPV_FORMAT_FLAG
                "external"          MPV_FORMAT_FLAG
                "external-filename" MPV_FORMAT_STRING
                "codec"             MPV_FORMAT_STRING
                "ff-index"          MPV_FORMAT_INT64
                "decoder-desc"      MPV_FORMAT_STRING
                "demux-w"           MPV_FORMAT_INT64
                "demux-h"           MPV_FORMAT_INT64
                "demux-channel-count" MPV_FORMAT_INT64
                "demux-channels"    MPV_FORMAT_STRING
                "demux-samplerate"  MPV_FORMAT_INT64
                "demux-fps"         MPV_FORMAT_DOUBLE
                "audio-channels"    MPV_FORMAT_INT64
                "replaygain-track-peak" MPV_FORMAT_DOUBLE
                "replaygain-track-gain" MPV_FORMAT_DOUBLE
                "replaygain-album-peak" MPV_FORMAT_DOUBLE
                "replaygain-album-gain" MPV_FORMAT_DOUBLE

``chapter-list``
    List of chapters, current entry marked. Currently, the raw property value
    is useless.

    This has a number of sub-properties. Replace ``N`` with the 0-based chapter
    index.

    ``chapter-list/count``
        Number of chapters.

    ``chapter-list/N/title``
        Chapter title as stored in the file. Not always available.

    ``chapter-list/N/time``
        Chapter start time in seconds as float.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP (for each chapter)
                "title" MPV_FORMAT_STRING
                "time"  MPV_FORMAT_DOUBLE

``af``, ``vf`` (RW)
    See ``--vf``/``--af`` and the ``vf``/``af`` command.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP (for each filter entry)
                "name"      MPV_FORMAT_STRING
                "label"     MPV_FORMAT_STRING [optional]
                "enabled"   MPV_FORMAT_FLAG [optional]
                "params"    MPV_FORMAT_NODE_MAP [optional]
                    "key"   MPV_FORMAT_STRING
                    "value" MPV_FORMAT_STRING

    It's also possible to write the property using this format.

``seekable``
    Return whether it's generally possible to seek in the current file.

``partially-seekable``
    Return ``yes`` if the current file is considered seekable, but only because
    the cache is active. This means small relative seeks may be fine, but larger
    seeks may fail anyway. Whether a seek will succeed or not is generally not
    known in advance.

    If this property returns true, ``seekable`` will also return true.

``playback-abort``
    Return whether playback is stopped or is to be stopped. (Useful in obscure
    situations like during ``on_load`` hook processing, when the user can
    stop playback, but the script has to explicitly end processing.)

``cursor-autohide`` (RW)
    See ``--cursor-autohide``. Setting this to a new value will always update
    the cursor, and reset the internal timer.

``osd-sym-cc``
    Inserts the current OSD symbol as opaque OSD control code (cc). This makes
    sense only with the ``show-text`` command or options which set OSD messages.
    The control code is implementation specific and is useless for anything else.

``osd-ass-cc``
    ``${osd-ass-cc/0}`` disables escaping ASS sequences of text in OSD,
    ``${osd-ass-cc/1}`` enables it again. By default, ASS sequences are
    escaped to avoid accidental formatting, and this property can disable
    this behavior. Note that the properties return an opaque OSD control
    code, which only makes sense for the ``show-text`` command or options
    which set OSD messages.

    .. admonition:: Example

        - ``--osd-status-msg='This is ${osd-ass-cc/0}{\\b1}bold text'``
        - ``show-text "This is ${osd-ass-cc/0}{\b1}bold text"``

    Any ASS override tags as understood by libass can be used.

    Note that you need to escape the ``\`` character, because the string is
    processed for C escape sequences before passing it to the OSD code.

    A list of tags can be found here: http://docs.aegisub.org/latest/ASS_Tags/

``vo-configured``
    Return whether the VO is configured right now. Usually this corresponds to
    whether the video window is visible. If the ``--force-window`` option is
    used, this is usually always returns ``yes``.

``vo-passes``
    Contains introspection about the VO's active render passes and their
    execution times. Not implemented by all VOs.

    This is further subdivided into two frame types, ``vo-passes/fresh`` for
    fresh frames (which have to be uploaded, scaled, etc.) and
    ``vo-passes/redraw`` for redrawn frames (which only have to be re-painted).
    The number of passes for any given subtype can change from frame to frame,
    and should not be relied upon.

    Each frame type has a number of further sub-properties. Replace ``TYPE``
    with the frame type, ``N`` with the 0-based pass index, and ``M`` with the
    0-based sample index.

    ``vo-passes/TYPE/count``
        Number of passes.

    ``vo-passes/TYPE/N/desc``
        Human-friendy description of the pass.

    ``vo-passes/TYPE/N/last``
        Last measured execution time, in nanoseconds.

    ``vo-passes/TYPE/N/avg``
        Average execution time of this pass, in nanoseconds. The exact
        timeframe varies, but it should generally be a handful of seconds.

    ``vo-passes/TYPE/N/peak``
        The peak execution time (highest value) within this averaging range, in
        nanoseconds.

    ``vo-passes/TYPE/N/count``
        The number of samples for this pass.

    ``vo-passes/TYPE/N/samples/M``
        The raw execution time of a specific sample for this pass, in
        nanoseconds.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_MAP
        "TYPE" MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP
                "desc"    MPV_FORMAT_STRING
                "last"    MPV_FORMAT_INT64
                "avg"     MPV_FORMAT_INT64
                "peak"    MPV_FORMAT_INT64
                "count"   MPV_FORMAT_INT64
                "samples" MPV_FORMAT_NODE_ARRAY
                     MP_FORMAT_INT64

    Note that directly accessing this structure via subkeys is not supported,
    the only access is through aforementioned ``MPV_FORMAT_NODE``.

``video-bitrate``, ``audio-bitrate``, ``sub-bitrate``
    Bitrate values calculated on the packet level. This works by dividing the
    bit size of all packets between two keyframes by their presentation
    timestamp distance. (This uses the timestamps are stored in the file, so
    e.g. playback speed does not influence the returned values.) In particular,
    the video bitrate will update only per keyframe, and show the "past"
    bitrate. To make the property more UI friendly, updates to these properties
    are throttled in a certain way.

    The unit is bits per second. OSD formatting turns these values in kilobits
    (or megabits, if appropriate), which can be prevented by using the
    raw property value, e.g. with ``${=video-bitrate}``.

    Note that the accuracy of these properties is influenced by a few factors.
    If the underlying demuxer rewrites the packets on demuxing (done for some
    file formats), the bitrate might be slightly off. If timestamps are bad
    or jittery (like in Matroska), even constant bitrate streams might show
    fluctuating bitrate.

    How exactly these values are calculated might change in the future.

    In earlier versions of mpv, these properties returned a static (but bad)
    guess using a completely different method.

``packet-video-bitrate``, ``packet-audio-bitrate``, ``packet-sub-bitrate``
    Old and deprecated properties for ``video-bitrate``, ``audio-bitrate``,
    ``sub-bitrate``. They behave exactly the same, but return a value in
    kilobits. Also, they don't have any OSD formatting, though the same can be
    achieved with e.g. ``${=video-bitrate}``.

    These properties shouldn't be used anymore.

``audio-device-list``
    Return the list of discovered audio devices. This is mostly for use with
    the client API, and reflects what ``--audio-device=help`` with the command
    line player returns.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP (for each device entry)
                "name"          MPV_FORMAT_STRING
                "description"   MPV_FORMAT_STRING

    The ``name`` is what is to be passed to the ``--audio-device`` option (and
    often a rather cryptic audio API-specific ID), while ``description`` is
    human readable free form text. The description is set to the device name
    (minus mpv-specific ``<driver>/`` prefix) if no description is available
    or the description would have been an empty string.

    The special entry with the name set to ``auto`` selects the default audio
    output driver and the default device.

    The property can be watched with the property observation mechanism in
    the client API and in Lua scripts. (Technically, change notification is
    enabled the first time this property is read.)

``audio-device`` (RW)
    Set the audio device. This directly reads/writes the ``--audio-device``
    option, but on write accesses, the audio output will be scheduled for
    reloading.

    Writing this property while no audio output is active will not automatically
    enable audio. (This is also true in the case when audio was disabled due to
    reinitialization failure after a previous write access to ``audio-device``.)

    This property also doesn't tell you which audio device is actually in use.

    How these details are handled may change in the future.

``current-vo``
    Current video output driver (name as used with ``--vo``).

``current-ao``
    Current audio output driver (name as used with ``--ao``).

``working-directory``
    Return the working directory of the mpv process. Can be useful for JSON IPC
    users, because the command line player usually works with relative paths.

``protocol-list``
    List of protocol prefixes potentially recognized by the player. They are
    returned without trailing ``://`` suffix (which is still always required).
    In some cases, the protocol will not actually be supported (consider
    ``https`` if ffmpeg is not compiled with TLS support).

``decoder-list``
    List of decoders supported. This lists decoders which can be passed to
    ``--vd`` and ``--ad``.

    ``family``
        Decoder driver. Usually ``lavc`` for libavcodec.

    ``codec``
        Canonical codec name, which identifies the format the decoder can
        handle.

    ``driver``
        The name of the decoder itself. Often, this is the same as ``codec``.
        Sometimes it can be different. It is used to distinguish multiple
        decoders for the same codec.

    ``description``
        Human readable description of the decoder and codec.

    When querying the property with the client API using ``MPV_FORMAT_NODE``,
    or with Lua ``mp.get_property_native``, this will return a mpv_node with
    the following contents:

    ::

        MPV_FORMAT_NODE_ARRAY
            MPV_FORMAT_NODE_MAP (for each decoder entry)
                "family"        MPV_FORMAT_STRING
                "codec"         MPV_FORMAT_STRING
                "driver"        MPV_FORMAT_STRING
                "description"   MPV_FORMAT_STRING

``encoder-list``
    List of libavcodec encoders. This has the same format as ``decoder-list``.
    The encoder names (``driver`` entries) can be passed to ``--ovc`` and
    ``--oac`` (without the ``lavc:`` prefix required by ``--vd`` and ``--ad``).

``mpv-version``
    Return the mpv version/copyright string. Depending on how the binary was
    built, it might contain either a release version, or just a git hash.

``mpv-configuration``
    Return the configuration arguments which were passed to the build system
    (typically the way ``./waf configure ...`` was invoked).

``ffmpeg-version``
    Return the contents of the ``av_version_info()`` API call. This is a string
    which identifies the build in some way, either through a release version
    number, or a git hash. This applies to Libav as well (the property is
    still named the same.) This property is unavailable if mpv is linked against
    older FFmpeg and Libav versions.

``options/<name>`` (RW)
    Read-only access to value of option ``--<name>``. Most options can be
    changed at runtime by writing to this property. Note that many options
    require reloading the file for changes to take effect. If there is an
    equivalent property, prefer setting the property instead.

    There shouldn't be any reason to access ``options/<name>`` instead of
    ``<name>``, except in situations in which the properties have different
    behavior or conflicting semantics.

``file-local-options/<name>``
    Similar to ``options/<name>``, but when setting an option through this
    property, the option is reset to its old value once the current file has
    stopped playing. Trying to write an option while no file is playing (or
    is being loaded) results in an error.

    (Note that if an option is marked as file-local, even ``options/`` will
    access the local value, and the ``old`` value, which will be restored on
    end of playback, cannot be read or written until end of playback.)

``option-info/<name>``
    Additional per-option information.

    This has a number of sub-properties. Replace ``<name>`` with the name of
    a top-level option. No guarantee of stability is given to any of these
    sub-properties - they may change radically in the feature.

    ``option-info/<name>/name``
        Returns the name of the option.

    ``option-info/<name>/type``
        Return the name of the option type, like ``String`` or ``Integer``.
        For many complex types, this isn't very accurate.

    ``option-info/<name>/set-from-commandline``
        Return ``yes`` if the option was set from the mpv command line,
        ``no`` otherwise. What this is set to if the option is e.g. changed
        at runtime is left undefined (meaning it could change in the future).

    ``option-info/<name>/set-locally``
        Return ``yes`` if the option was set per-file. This is the case with
        automatically loaded profiles, file-dir configs, and other cases. It
        means the option value will be restored to the value before playback
        start when playback ends.

    ``option-info/<name>/default-value``
        The default value of the option. May not always be available.

    ``option-info/<name>/min``, ``option-info/<name>/max``
        Integer minimum and maximum values allowed for the option. Only
        available if the options are numeric, and the minimum/maximum has been
        set internally. It's also possible that only one of these is set.

    ``option-info/<name>/choices``
        If the option is a choice option, the possible choices. Choices that
        are integers may or may not be included (they can be implied by ``min``
        and ``max``). Note that options which behave like choice options, but
        are not actual choice options internally, may not have this info
        available.

``property-list``
    Return the list of top-level properties.

``profile-list``
    Return the list of profiles and their contents. This is highly
    implementation-specific, and may change any time. Currently, it returns
    an array of options for each profile. Each option has a name and a value,
    with the value currently always being a string. Note that the options array
    is not a map, as order matters and duplicate entries are possible. Recursive
    profiles are not expanded, and show up as special ``profile`` options.

Inconsistencies between options and properties
----------------------------------------------

You can access (almost) all options as properties, though there are some
caveats with some properties (due to historical reasons):

``vid``, ``aid``, ``sid``
    While playback is active, you can set existing tracks only. (The option
    allows setting any track ID, and which tracks to enable is chosen at
    loading time.)

    Option changes at runtime are affected by this as well.

``video-aspect``
    While video is active, always returns the effective aspect ratio. Setting
    a special value (like ``no``, values ``<= 0``) will make the property
    set this as option, and return whatever actual aspect was derived from the
    option setting.

``display-fps``
    If a VO is created, this will return either the actual display FPS, or
    an invalid value, instead of the option value.

``vf``, ``af``
    If you set the properties during playback, and the filter chain fails to
    reinitialize, the new value will be rejected. Setting the option or
    setting the property outside of playback will always succeed/fail in the
    same way. Also, there are no ``vf-add`` etc. properties, but you can use
    the ``vf``/``af`` group of commands to achieve the same.

    Option changes at runtime are affected by this as well.

``edition``
    While a file is loaded, the property will always return the effective
    edition, and setting the ``auto`` value will show somewhat strange behavior
    (the property eventually switching to whatever is the default edition).

``playlist``
    The property is read-only and returns the current internal playlist. The
    option is for loading playlist during command line parsing. For client API
    uses, you should use the ``loadlist`` command instead.

``window-scale``
    Might verify the set value when setting while a window is created.

``audio-file``, ``sub-file``, ``external-file``
    These options/properties are actually lists of filenames. To make the
    command-line interface easier, each ``--audio-file=...`` option appends
    the full string to the internal list. However, when used as properties,
    every time you set the property as a string the internal list will be
    replaced with a single entry containing the string you set. ``,`` or other
    separators are never used. You have to use ``MPV_FORMAT_NODE_ARRAY`` (or
    corresponding API, e.g. ``mp.set_property_native()`` with a table in Lua)
    to set multiple entries.

    Strictly speaking, option access via API (e.g. ``mpv_set_option_string()``)
    has the same problem, and it's only a difference between CLI/API.

``playlist-pos``, ``chapter``
    These properties behave different from the deprecated options with the same
    names.

``profile``, ``include``
    These are write-only, and will perform actions as they are written to,
    exactly as if they were used on the mpv CLI commandline. Their only use is
    when using libmpv before ``mpv_initialize()``, which in turn is probably
    only useful in encoding mode. Normal libmpv users should use other
    mechanisms, such as the ``apply-profile`` command, and the
    ``mpv_load_config_file`` API function. Avoid these properties.

Property Expansion
------------------

All string arguments to input commands as well as certain options (like
``--term-playing-msg``) are subject to property expansion. Note that property
expansion does not work in places where e.g. numeric parameters are expected.
(For example, the ``add`` command does not do property expansion. The ``set``
command is an exception and not a general rule.)

.. admonition:: Example for input.conf

    ``i show-text "Filename: ${filename}"``
        shows the filename of the current file when pressing the ``i`` key

Within ``input.conf``, property expansion can be inhibited by putting the
``raw`` prefix in front of commands.

The following expansions are supported:

``${NAME}``
    Expands to the value of the property ``NAME``. If retrieving the property
    fails, expand to an error string. (Use ``${NAME:}`` with a trailing
    ``:`` to expand to an empty string instead.)
    If ``NAME`` is prefixed with ``=``, expand to the raw value of the property
    (see section below).
``${NAME:STR}``
    Expands to the value of the property ``NAME``, or ``STR`` if the
    property cannot be retrieved. ``STR`` is expanded recursively.
``${?NAME:STR}``
    Expands to ``STR`` (recursively) if the property ``NAME`` is available.
``${!NAME:STR}``
    Expands to ``STR`` (recursively) if the property ``NAME`` cannot be
    retrieved.
``${?NAME==VALUE:STR}``
    Expands to ``STR`` (recursively) if the property ``NAME`` expands to a
    string equal to ``VALUE``. You can prefix ``NAME`` with ``=`` in order to
    compare the raw value of a property (see section below). If the property
    is unavailable, or other errors happen when retrieving it, the value is
    never considered equal.
    Note that ``VALUE`` can't contain any of the characters ``:`` or ``}``.
    Also, it is possible that escaping with ``"`` or ``%`` might be added in
    the future, should the need arise.
``${!NAME==VALUE:STR}``
    Same as with the ``?`` variant, but ``STR`` is expanded if the value is
    not equal. (Using the same semantics as with ``?``.)
``$$``
    Expands to ``$``.
``$}``
    Expands to ``}``. (To produce this character inside recursive
    expansion.)
``$>``
    Disable property expansion and special handling of ``$`` for the rest
    of the string.

In places where property expansion is allowed, C-style escapes are often
accepted as well. Example:

    - ``\n`` becomes a newline character
    - ``\\`` expands to ``\``

Raw and Formatted Properties
----------------------------

Normally, properties are formatted as human-readable text, meant to be
displayed on OSD or on the terminal. It is possible to retrieve an unformatted
(raw) value from a property by prefixing its name with ``=``. These raw values
can be parsed by other programs and follow the same conventions as the options
associated with the properties.

.. admonition:: Examples

    - ``${time-pos}`` expands to ``00:14:23`` (if playback position is at 14
      minutes 23 seconds)
    - ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds -
      milliseconds are normally not shown in the formatted case)

Sometimes, the difference in amount of information carried by raw and formatted
property values can be rather big. In some cases, raw values have more
information, like higher precision than seconds with ``time-pos``. Sometimes
it is the other way around, e.g. ``aid`` shows track title and language in the
formatted case, but only the track number if it is raw.