/usr/include/vlc/libvlc_media_player.h is in libvlc-dev 2.1.2-2build2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | /*****************************************************************************
* libvlc_media_player.h: libvlc_media_player external API
*****************************************************************************
* Copyright (C) 1998-2010 VLC authors and VideoLAN
* $Id: 82c7ac2cfd2ecf05449a3ee22bcb2a23420d413a $
*
* Authors: Clément Stenac <zorglub@videolan.org>
* Jean-Paul Saman <jpsaman@videolan.org>
* Pierre d'Herbemont <pdherbemont@videolan.org>
*
* This program is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 2.1 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
* \file
* This file defines libvlc_media_player external API
*/
#ifndef VLC_LIBVLC_MEDIA_PLAYER_H
#define VLC_LIBVLC_MEDIA_PLAYER_H 1
# ifdef __cplusplus
extern "C" {
# else
# include <stdbool.h>
# endif
/*****************************************************************************
* Media Player
*****************************************************************************/
/** \defgroup libvlc_media_player LibVLC media player
* \ingroup libvlc
* A LibVLC media player plays one media (usually in a custom drawable).
* @{
*/
typedef struct libvlc_media_player_t libvlc_media_player_t;
/**
* Description for video, audio tracks and subtitles. It contains
* id, name (description string) and pointer to next record.
*/
typedef struct libvlc_track_description_t
{
int i_id;
char *psz_name;
struct libvlc_track_description_t *p_next;
} libvlc_track_description_t;
/**
* Description for audio output. It contains
* name, description and pointer to next record.
*/
typedef struct libvlc_audio_output_t
{
char *psz_name;
char *psz_description;
struct libvlc_audio_output_t *p_next;
} libvlc_audio_output_t;
/**
* Description for audio output device.
*/
typedef struct libvlc_audio_output_device_t
{
struct libvlc_audio_output_device_t *p_next; /**< Next entry in list */
char *psz_device; /**< Device identifier string */
char *psz_description; /**< User-friendly device description */
/* More fields may be added here in later versions */
} libvlc_audio_output_device_t;
/**
* Rectangle type for video geometry
*/
typedef struct libvlc_rectangle_t
{
int top, left;
int bottom, right;
} libvlc_rectangle_t;
/**
* Marq options definition
*/
typedef enum libvlc_video_marquee_option_t {
libvlc_marquee_Enable = 0,
libvlc_marquee_Text, /** string argument */
libvlc_marquee_Color,
libvlc_marquee_Opacity,
libvlc_marquee_Position,
libvlc_marquee_Refresh,
libvlc_marquee_Size,
libvlc_marquee_Timeout,
libvlc_marquee_X,
libvlc_marquee_Y
} libvlc_video_marquee_option_t;
/**
* Navigation mode
*/
typedef enum libvlc_navigate_mode_t
{
libvlc_navigate_activate = 0,
libvlc_navigate_up,
libvlc_navigate_down,
libvlc_navigate_left,
libvlc_navigate_right
} libvlc_navigate_mode_t;
/**
* Enumeration of values used to set position (e.g. of video title).
*/
typedef enum libvlc_position_t {
libvlc_position_disable=-1,
libvlc_position_center,
libvlc_position_left,
libvlc_position_right,
libvlc_position_top,
libvlc_position_top_left,
libvlc_position_top_right,
libvlc_position_bottom,
libvlc_position_bottom_left,
libvlc_position_bottom_right
} libvlc_position_t;
/**
* Create an empty Media Player object
*
* \param p_libvlc_instance the libvlc instance in which the Media Player
* should be created.
* \return a new media player object, or NULL on error.
*/
LIBVLC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p_libvlc_instance );
/**
* Create a Media Player object from a Media
*
* \param p_md the media. Afterwards the p_md can be safely
* destroyed.
* \return a new media player object, or NULL on error.
*/
LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *p_md );
/**
* Release a media_player after use
* Decrement the reference count of a media player object. If the
* reference count is 0, then libvlc_media_player_release() will
* release the media player object. If the media player object
* has been released, then it should not be used again.
*
* \param p_mi the Media Player to free
*/
LIBVLC_API void libvlc_media_player_release( libvlc_media_player_t *p_mi );
/**
* Retain a reference to a media player object. Use
* libvlc_media_player_release() to decrement reference count.
*
* \param p_mi media player object
*/
LIBVLC_API void libvlc_media_player_retain( libvlc_media_player_t *p_mi );
/**
* Set the media that will be used by the media_player. If any,
* previous md will be released.
*
* \param p_mi the Media Player
* \param p_md the Media. Afterwards the p_md can be safely
* destroyed.
*/
LIBVLC_API void libvlc_media_player_set_media( libvlc_media_player_t *p_mi,
libvlc_media_t *p_md );
/**
* Get the media used by the media_player.
*
* \param p_mi the Media Player
* \return the media associated with p_mi, or NULL if no
* media is associated
*/
LIBVLC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t *p_mi );
/**
* Get the Event Manager from which the media player send event.
*
* \param p_mi the Media Player
* \return the event manager associated with p_mi
*/
LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *p_mi );
/**
* is_playing
*
* \param p_mi the Media Player
* \return 1 if the media player is playing, 0 otherwise
*
* \libvlc_return_bool
*/
LIBVLC_API int libvlc_media_player_is_playing ( libvlc_media_player_t *p_mi );
/**
* Play
*
* \param p_mi the Media Player
* \return 0 if playback started (and was already started), or -1 on error.
*/
LIBVLC_API int libvlc_media_player_play ( libvlc_media_player_t *p_mi );
/**
* Pause or resume (no effect if there is no media)
*
* \param mp the Media Player
* \param do_pause play/resume if zero, pause if non-zero
* \version LibVLC 1.1.1 or later
*/
LIBVLC_API void libvlc_media_player_set_pause ( libvlc_media_player_t *mp,
int do_pause );
/**
* Toggle pause (no effect if there is no media)
*
* \param p_mi the Media Player
*/
LIBVLC_API void libvlc_media_player_pause ( libvlc_media_player_t *p_mi );
/**
* Stop (no effect if there is no media)
*
* \param p_mi the Media Player
*/
LIBVLC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi );
/**
* Callback prototype to allocate and lock a picture buffer.
*
* Whenever a new video frame needs to be decoded, the lock callback is
* invoked. Depending on the video chroma, one or three pixel planes of
* adequate dimensions must be returned via the second parameter. Those
* planes must be aligned on 32-bytes boundaries.
*
* \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
* \param planes start address of the pixel planes (LibVLC allocates the array
* of void pointers, this callback must initialize the array) [OUT]
* \return a private pointer for the display and unlock callbacks to identify
* the picture buffers
*/
typedef void *(*libvlc_video_lock_cb)(void *opaque, void **planes);
/**
* Callback prototype to unlock a picture buffer.
*
* When the video frame decoding is complete, the unlock callback is invoked.
* This callback might not be needed at all. It is only an indication that the
* application can now read the pixel values if it needs to.
*
* \warning A picture buffer is unlocked after the picture is decoded,
* but before the picture is displayed.
*
* \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
* \param picture private pointer returned from the @ref libvlc_video_lock_cb
* callback [IN]
* \param planes pixel planes as defined by the @ref libvlc_video_lock_cb
* callback (this parameter is only for convenience) [IN]
*/
typedef void (*libvlc_video_unlock_cb)(void *opaque, void *picture,
void *const *planes);
/**
* Callback prototype to display a picture.
*
* When the video frame needs to be shown, as determined by the media playback
* clock, the display callback is invoked.
*
* \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
* \param picture private pointer returned from the @ref libvlc_video_lock_cb
* callback [IN]
*/
typedef void (*libvlc_video_display_cb)(void *opaque, void *picture);
/**
* Callback prototype to configure picture buffers format.
* This callback gets the format of the video as output by the video decoder
* and the chain of video filters (if any). It can opt to change any parameter
* as it needs. In that case, LibVLC will attempt to convert the video format
* (rescaling and chroma conversion) but these operations can be CPU intensive.
*
* \param opaque pointer to the private pointer passed to
* libvlc_video_set_callbacks() [IN/OUT]
* \param chroma pointer to the 4 bytes video format identifier [IN/OUT]
* \param width pointer to the pixel width [IN/OUT]
* \param height pointer to the pixel height [IN/OUT]
* \param pitches table of scanline pitches in bytes for each pixel plane
* (the table is allocated by LibVLC) [OUT]
* \param lines table of scanlines count for each plane [OUT]
* \return the number of picture buffers allocated, 0 indicates failure
*
* \note
* For each pixels plane, the scanline pitch must be bigger than or equal to
* the number of bytes per pixel multiplied by the pixel width.
* Similarly, the number of scanlines must be bigger than of equal to
* the pixel height.
* Furthermore, we recommend that pitches and lines be multiple of 32
* to not break assumption that might be made by various optimizations
* in the video decoders, video filters and/or video converters.
*/
typedef unsigned (*libvlc_video_format_cb)(void **opaque, char *chroma,
unsigned *width, unsigned *height,
unsigned *pitches,
unsigned *lines);
/**
* Callback prototype to configure picture buffers format.
*
* \param opaque private pointer as passed to libvlc_video_set_callbacks()
* (and possibly modified by @ref libvlc_video_format_cb) [IN]
*/
typedef void (*libvlc_video_cleanup_cb)(void *opaque);
/**
* Set callbacks and private data to render decoded video to a custom area
* in memory.
* Use libvlc_video_set_format() or libvlc_video_set_format_callbacks()
* to configure the decoded format.
*
* \param mp the media player
* \param lock callback to lock video memory (must not be NULL)
* \param unlock callback to unlock video memory (or NULL if not needed)
* \param display callback to display video (or NULL if not needed)
* \param opaque private pointer for the three callbacks (as first parameter)
* \version LibVLC 1.1.1 or later
*/
LIBVLC_API
void libvlc_video_set_callbacks( libvlc_media_player_t *mp,
libvlc_video_lock_cb lock,
libvlc_video_unlock_cb unlock,
libvlc_video_display_cb display,
void *opaque );
/**
* Set decoded video chroma and dimensions.
* This only works in combination with libvlc_video_set_callbacks(),
* and is mutually exclusive with libvlc_video_set_format_callbacks().
*
* \param mp the media player
* \param chroma a four-characters string identifying the chroma
* (e.g. "RV32" or "YUYV")
* \param width pixel width
* \param height pixel height
* \param pitch line pitch (in bytes)
* \version LibVLC 1.1.1 or later
* \bug All pixel planes are expected to have the same pitch.
* To use the YCbCr color space with chrominance subsampling,
* consider using libvlc_video_set_format_callbacks() instead.
*/
LIBVLC_API
void libvlc_video_set_format( libvlc_media_player_t *mp, const char *chroma,
unsigned width, unsigned height,
unsigned pitch );
/**
* Set decoded video chroma and dimensions. This only works in combination with
* libvlc_video_set_callbacks().
*
* \param mp the media player
* \param setup callback to select the video format (cannot be NULL)
* \param cleanup callback to release any allocated resources (or NULL)
* \version LibVLC 2.0.0 or later
*/
LIBVLC_API
void libvlc_video_set_format_callbacks( libvlc_media_player_t *mp,
libvlc_video_format_cb setup,
libvlc_video_cleanup_cb cleanup );
/**
* Set the NSView handler where the media player should render its video output.
*
* Use the vout called "macosx".
*
* The drawable is an NSObject that follow the VLCOpenGLVideoViewEmbedding
* protocol:
*
* @begincode
* \@protocol VLCOpenGLVideoViewEmbedding <NSObject>
* - (void)addVoutSubview:(NSView *)view;
* - (void)removeVoutSubview:(NSView *)view;
* \@end
* @endcode
*
* Or it can be an NSView object.
*
* If you want to use it along with Qt4 see the QMacCocoaViewContainer. Then
* the following code should work:
* @begincode
* {
* NSView *video = [[NSView alloc] init];
* QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
* libvlc_media_player_set_nsobject(mp, video);
* [video release];
* }
* @endcode
*
* You can find a live example in VLCVideoView in VLCKit.framework.
*
* \param p_mi the Media Player
* \param drawable the drawable that is either an NSView or an object following
* the VLCOpenGLVideoViewEmbedding protocol.
*/
LIBVLC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable );
/**
* Get the NSView handler previously set with libvlc_media_player_set_nsobject().
*
* \param p_mi the Media Player
* \return the NSView handler or 0 if none where set
*/
LIBVLC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi );
/**
* Set the agl handler where the media player should render its video output.
*
* \param p_mi the Media Player
* \param drawable the agl handler
*/
LIBVLC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable );
/**
* Get the agl handler previously set with libvlc_media_player_set_agl().
*
* \param p_mi the Media Player
* \return the agl handler or 0 if none where set
*/
LIBVLC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_mi );
/**
* Set an X Window System drawable where the media player should render its
* video output. If LibVLC was built without X11 output support, then this has
* no effects.
*
* The specified identifier must correspond to an existing Input/Output class
* X11 window. Pixmaps are <b>not</b> supported. The caller shall ensure that
* the X11 server is the same as the one the VLC instance has been configured
* with. This function must be called before video playback is started;
* otherwise it will only take effect after playback stop and restart.
*
* \param p_mi the Media Player
* \param drawable the ID of the X window
*/
LIBVLC_API void libvlc_media_player_set_xwindow ( libvlc_media_player_t *p_mi, uint32_t drawable );
/**
* Get the X Window System window identifier previously set with
* libvlc_media_player_set_xwindow(). Note that this will return the identifier
* even if VLC is not currently using it (for instance if it is playing an
* audio-only input).
*
* \param p_mi the Media Player
* \return an X window ID, or 0 if none where set.
*/
LIBVLC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi );
/**
* Set a Win32/Win64 API window handle (HWND) where the media player should
* render its video output. If LibVLC was built without Win32/Win64 API output
* support, then this has no effects.
*
* \param p_mi the Media Player
* \param drawable windows handle of the drawable
*/
LIBVLC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable );
/**
* Get the Windows API window handle (HWND) previously set with
* libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC
* is not currently outputting any video to it.
*
* \param p_mi the Media Player
* \return a window handle or NULL if there are none.
*/
LIBVLC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );
/**
* Callback prototype for audio playback.
* \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
* \param samples pointer to the first audio sample to play back [IN]
* \param count number of audio samples to play back
* \param pts expected play time stamp (see libvlc_delay())
*/
typedef void (*libvlc_audio_play_cb)(void *data, const void *samples,
unsigned count, int64_t pts);
/**
* Callback prototype for audio pause.
* \note The pause callback is never called if the audio is already paused.
* \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
* \param pts time stamp of the pause request (should be elapsed already)
*/
typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts);
/**
* Callback prototype for audio resumption (i.e. restart from pause).
* \note The resume callback is never called if the audio is not paused.
* \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
* \param pts time stamp of the resumption request (should be elapsed already)
*/
typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts);
/**
* Callback prototype for audio buffer flush
* (i.e. discard all pending buffers and stop playback as soon as possible).
* \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
*/
typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts);
/**
* Callback prototype for audio buffer drain
* (i.e. wait for pending buffers to be played).
* \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
*/
typedef void (*libvlc_audio_drain_cb)(void *data);
/**
* Callback prototype for audio volume change.
* \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
* \param volume software volume (1. = nominal, 0. = mute)
* \param mute muted flag
*/
typedef void (*libvlc_audio_set_volume_cb)(void *data,
float volume, bool mute);
/**
* Set callbacks and private data for decoded audio.
* Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
* to configure the decoded audio format.
*
* \param mp the media player
* \param play callback to play audio samples (must not be NULL)
* \param pause callback to pause playback (or NULL to ignore)
* \param resume callback to resume playback (or NULL to ignore)
* \param flush callback to flush audio buffers (or NULL to ignore)
* \param drain callback to drain audio buffers (or NULL to ignore)
* \param opaque private pointer for the audio callbacks (as first parameter)
* \version LibVLC 2.0.0 or later
*/
LIBVLC_API
void libvlc_audio_set_callbacks( libvlc_media_player_t *mp,
libvlc_audio_play_cb play,
libvlc_audio_pause_cb pause,
libvlc_audio_resume_cb resume,
libvlc_audio_flush_cb flush,
libvlc_audio_drain_cb drain,
void *opaque );
/**
* Set callbacks and private data for decoded audio.
* Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
* to configure the decoded audio format.
*
* \param mp the media player
* \param set_volume callback to apply audio volume,
* or NULL to apply volume in software
* \version LibVLC 2.0.0 or later
*/
LIBVLC_API
void libvlc_audio_set_volume_callback( libvlc_media_player_t *mp,
libvlc_audio_set_volume_cb set_volume );
/**
* Callback prototype to setup the audio playback.
* This is called when the media player needs to create a new audio output.
* \param opaque pointer to the data pointer passed to
* libvlc_audio_set_callbacks() [IN/OUT]
* \param format 4 bytes sample format [IN/OUT]
* \param rate sample rate [IN/OUT]
* \param channels channels count [IN/OUT]
* \return 0 on success, anything else to skip audio playback
*/
typedef int (*libvlc_audio_setup_cb)(void **data, char *format, unsigned *rate,
unsigned *channels);
/**
* Callback prototype for audio playback cleanup.
* This is called when the media player no longer needs an audio output.
* \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN]
*/
typedef void (*libvlc_audio_cleanup_cb)(void *data);
/**
* Set decoded audio format. This only works in combination with
* libvlc_audio_set_callbacks().
*
* \param mp the media player
* \param setup callback to select the audio format (cannot be NULL)
* \param cleanup callback to release any allocated resources (or NULL)
* \version LibVLC 2.0.0 or later
*/
LIBVLC_API
void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp,
libvlc_audio_setup_cb setup,
libvlc_audio_cleanup_cb cleanup );
/**
* Set decoded audio format.
* This only works in combination with libvlc_audio_set_callbacks(),
* and is mutually exclusive with libvlc_audio_set_format_callbacks().
*
* \param mp the media player
* \param format a four-characters string identifying the sample format
* (e.g. "S16N" or "FL32")
* \param rate sample rate (expressed in Hz)
* \param channels channels count
* \version LibVLC 2.0.0 or later
*/
LIBVLC_API
void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format,
unsigned rate, unsigned channels );
/** \bug This might go away ... to be replaced by a broader system */
/**
* Get the current movie length (in ms).
*
* \param p_mi the Media Player
* \return the movie length (in ms), or -1 if there is no media.
*/
LIBVLC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *p_mi );
/**
* Get the current movie time (in ms).
*
* \param p_mi the Media Player
* \return the movie time (in ms), or -1 if there is no media.
*/
LIBVLC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *p_mi );
/**
* Set the movie time (in ms). This has no effect if no media is being played.
* Not all formats and protocols support this.
*
* \param p_mi the Media Player
* \param i_time the movie time (in ms).
*/
LIBVLC_API void libvlc_media_player_set_time( libvlc_media_player_t *p_mi, libvlc_time_t i_time );
/**
* Get movie position as percentage between 0.0 and 1.0.
*
* \param p_mi the Media Player
* \return movie position, or -1. in case of error
*/
LIBVLC_API float libvlc_media_player_get_position( libvlc_media_player_t *p_mi );
/**
* Set movie position as percentage between 0.0 and 1.0.
* This has no effect if playback is not enabled.
* This might not work depending on the underlying input format and protocol.
*
* \param p_mi the Media Player
* \param f_pos the position
*/
LIBVLC_API void libvlc_media_player_set_position( libvlc_media_player_t *p_mi, float f_pos );
/**
* Set movie chapter (if applicable).
*
* \param p_mi the Media Player
* \param i_chapter chapter number to play
*/
LIBVLC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *p_mi, int i_chapter );
/**
* Get movie chapter.
*
* \param p_mi the Media Player
* \return chapter number currently playing, or -1 if there is no media.
*/
LIBVLC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *p_mi );
/**
* Get movie chapter count
*
* \param p_mi the Media Player
* \return number of chapters in movie, or -1.
*/
LIBVLC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *p_mi );
/**
* Is the player able to play
*
* \param p_mi the Media Player
* \return boolean
*
* \libvlc_return_bool
*/
LIBVLC_API int libvlc_media_player_will_play( libvlc_media_player_t *p_mi );
/**
* Get title chapter count
*
* \param p_mi the Media Player
* \param i_title title
* \return number of chapters in title, or -1
*/
LIBVLC_API int libvlc_media_player_get_chapter_count_for_title(
libvlc_media_player_t *p_mi, int i_title );
/**
* Set movie title
*
* \param p_mi the Media Player
* \param i_title title number to play
*/
LIBVLC_API void libvlc_media_player_set_title( libvlc_media_player_t *p_mi, int i_title );
/**
* Get movie title
*
* \param p_mi the Media Player
* \return title number currently playing, or -1
*/
LIBVLC_API int libvlc_media_player_get_title( libvlc_media_player_t *p_mi );
/**
* Get movie title count
*
* \param p_mi the Media Player
* \return title number count, or -1
*/
LIBVLC_API int libvlc_media_player_get_title_count( libvlc_media_player_t *p_mi );
/**
* Set previous chapter (if applicable)
*
* \param p_mi the Media Player
*/
LIBVLC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t *p_mi );
/**
* Set next chapter (if applicable)
*
* \param p_mi the Media Player
*/
LIBVLC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *p_mi );
/**
* Get the requested movie play rate.
* @warning Depending on the underlying media, the requested rate may be
* different from the real playback rate.
*
* \param p_mi the Media Player
* \return movie play rate
*/
LIBVLC_API float libvlc_media_player_get_rate( libvlc_media_player_t *p_mi );
/**
* Set movie play rate
*
* \param p_mi the Media Player
* \param rate movie play rate to set
* \return -1 if an error was detected, 0 otherwise (but even then, it might
* not actually work depending on the underlying media protocol)
*/
LIBVLC_API int libvlc_media_player_set_rate( libvlc_media_player_t *p_mi, float rate );
/**
* Get current movie state
*
* \param p_mi the Media Player
* \return the current state of the media player (playing, paused, ...) \see libvlc_state_t
*/
LIBVLC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *p_mi );
/**
* Get movie fps rate
*
* \param p_mi the Media Player
* \return frames per second (fps) for this playing movie, or 0 if unspecified
*/
LIBVLC_API float libvlc_media_player_get_fps( libvlc_media_player_t *p_mi );
/** end bug */
/**
* How many video outputs does this media player have?
*
* \param p_mi the media player
* \return the number of video outputs
*/
LIBVLC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t *p_mi );
/**
* Is this media player seekable?
*
* \param p_mi the media player
* \return true if the media player can seek
*
* \libvlc_return_bool
*/
LIBVLC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi );
/**
* Can this media player be paused?
*
* \param p_mi the media player
* \return true if the media player can pause
*
* \libvlc_return_bool
*/
LIBVLC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi );
/**
* Display the next frame (if supported)
*
* \param p_mi the media player
*/
LIBVLC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi );
/**
* Navigate through DVD Menu
*
* \param p_mi the Media Player
* \param navigate the Navigation mode
* \version libVLC 2.0.0 or later
*/
LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi,
unsigned navigate );
/**
* Set if, and how, the video title will be shown when media is played.
*
* \param p_mi the media player
* \param position position at which to display the title, or libvlc_position_disable to prevent the title from being displayed
* \param timeout title display timeout in milliseconds (ignored if libvlc_position_disable)
* \version libVLC 2.1.0 or later
*/
LIBVLC_API void libvlc_media_player_set_video_title_display( libvlc_media_player_t *p_mi, libvlc_position_t position, unsigned int timeout );
/**
* Release (free) libvlc_track_description_t
*
* \param p_track_description the structure to release
*/
LIBVLC_API void libvlc_track_description_list_release( libvlc_track_description_t *p_track_description );
/**
* \deprecated Use libvlc_track_description_list_release instead
*/
LIBVLC_DEPRECATED LIBVLC_API
void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
/** \defgroup libvlc_video LibVLC video controls
* @{
*/
/**
* Toggle fullscreen status on non-embedded video outputs.
*
* @warning The same limitations applies to this function
* as to libvlc_set_fullscreen().
*
* \param p_mi the media player
*/
LIBVLC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *p_mi );
/**
* Enable or disable fullscreen.
*
* @warning With most window managers, only a top-level windows can be in
* full-screen mode. Hence, this function will not operate properly if
* libvlc_media_player_set_xwindow() was used to embed the video in a
* non-top-level window. In that case, the embedding window must be reparented
* to the root window <b>before</b> fullscreen mode is enabled. You will want
* to reparent it back to its normal parent when disabling fullscreen.
*
* \param p_mi the media player
* \param b_fullscreen boolean for fullscreen status
*/
LIBVLC_API void libvlc_set_fullscreen( libvlc_media_player_t *p_mi, int b_fullscreen );
/**
* Get current fullscreen status.
*
* \param p_mi the media player
* \return the fullscreen status (boolean)
*
* \libvlc_return_bool
*/
LIBVLC_API int libvlc_get_fullscreen( libvlc_media_player_t *p_mi );
/**
* Enable or disable key press events handling, according to the LibVLC hotkeys
* configuration. By default and for historical reasons, keyboard events are
* handled by the LibVLC video widget.
*
* \note On X11, there can be only one subscriber for key press and mouse
* click events per window. If your application has subscribed to those events
* for the X window ID of the video widget, then LibVLC will not be able to
* handle key presses and mouse clicks in any case.
*
* \warning This function is only implemented for X11 and Win32 at the moment.
*
* \param p_mi the media player
* \param on true to handle key press events, false to ignore them.
*/
LIBVLC_API
void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on );
/**
* Enable or disable mouse click events handling. By default, those events are
* handled. This is needed for DVD menus to work, as well as a few video
* filters such as "puzzle".
*
* \see libvlc_video_set_key_input().
*
* \warning This function is only implemented for X11 and Win32 at the moment.
*
* \param p_mi the media player
* \param on true to handle mouse click events, false to ignore them.
*/
LIBVLC_API
void libvlc_video_set_mouse_input( libvlc_media_player_t *p_mi, unsigned on );
/**
* Get the pixel dimensions of a video.
*
* \param p_mi media player
* \param num number of the video (starting from, and most commonly 0)
* \param px pointer to get the pixel width [OUT]
* \param py pointer to get the pixel height [OUT]
* \return 0 on success, -1 if the specified video does not exist
*/
LIBVLC_API
int libvlc_video_get_size( libvlc_media_player_t *p_mi, unsigned num,
unsigned *px, unsigned *py );
/**
* Get current video height.
* \deprecated Use libvlc_video_get_size() instead.
*
* \param p_mi the media player
* \return the video pixel height or 0 if not applicable
*/
LIBVLC_DEPRECATED LIBVLC_API
int libvlc_video_get_height( libvlc_media_player_t *p_mi );
/**
* Get current video width.
* \deprecated Use libvlc_video_get_size() instead.
*
* \param p_mi the media player
* \return the video pixel width or 0 if not applicable
*/
LIBVLC_DEPRECATED LIBVLC_API
int libvlc_video_get_width( libvlc_media_player_t *p_mi );
/**
* Get the mouse pointer coordinates over a video.
* Coordinates are expressed in terms of the decoded video resolution,
* <b>not</b> in terms of pixels on the screen/viewport (to get the latter,
* you can query your windowing system directly).
*
* Either of the coordinates may be negative or larger than the corresponding
* dimension of the video, if the cursor is outside the rendering area.
*
* @warning The coordinates may be out-of-date if the pointer is not located
* on the video rendering area. LibVLC does not track the pointer if it is
* outside of the video widget.
*
* @note LibVLC does not support multiple pointers (it does of course support
* multiple input devices sharing the same pointer) at the moment.
*
* \param p_mi media player
* \param num number of the video (starting from, and most commonly 0)
* \param px pointer to get the abscissa [OUT]
* \param py pointer to get the ordinate [OUT]
* \return 0 on success, -1 if the specified video does not exist
*/
LIBVLC_API
int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num,
int *px, int *py );
/**
* Get the current video scaling factor.
* See also libvlc_video_set_scale().
*
* \param p_mi the media player
* \return the currently configured zoom factor, or 0. if the video is set
* to fit to the output window/drawable automatically.
*/
LIBVLC_API float libvlc_video_get_scale( libvlc_media_player_t *p_mi );
/**
* Set the video scaling factor. That is the ratio of the number of pixels on
* screen to the number of pixels in the original decoded video in each
* dimension. Zero is a special value; it will adjust the video to the output
* window/drawable (in windowed mode) or the entire screen.
*
* Note that not all video outputs support scaling.
*
* \param p_mi the media player
* \param f_factor the scaling factor, or zero
*/
LIBVLC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f_factor );
/**
* Get current video aspect ratio.
*
* \param p_mi the media player
* \return the video aspect ratio or NULL if unspecified
* (the result must be released with free() or libvlc_free()).
*/
LIBVLC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi );
/**
* Set new video aspect ratio.
*
* \param p_mi the media player
* \param psz_aspect new video aspect-ratio or NULL to reset to default
* \note Invalid aspect ratios are ignored.
*/
LIBVLC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *p_mi, const char *psz_aspect );
/**
* Get current video subtitle.
*
* \param p_mi the media player
* \return the video subtitle selected, or -1 if none
*/
LIBVLC_API int libvlc_video_get_spu( libvlc_media_player_t *p_mi );
/**
* Get the number of available video subtitles.
*
* \param p_mi the media player
* \return the number of available video subtitles
*/
LIBVLC_API int libvlc_video_get_spu_count( libvlc_media_player_t *p_mi );
/**
* Get the description of available video subtitles.
*
* \param p_mi the media player
* \return list containing description of available video subtitles
*/
LIBVLC_API libvlc_track_description_t *
libvlc_video_get_spu_description( libvlc_media_player_t *p_mi );
/**
* Set new video subtitle.
*
* \param p_mi the media player
* \param i_spu video subtitle track to select (i_id from track description)
* \return 0 on success, -1 if out of range
*/
LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, int i_spu );
/**
* Set new video subtitle file.
*
* \param p_mi the media player
* \param psz_subtitle new video subtitle file
* \return the success status (boolean)
*/
LIBVLC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *p_mi, const char *psz_subtitle );
/**
* Get the current subtitle delay. Positive values means subtitles are being
* displayed later, negative values earlier.
*
* \param p_mi media player
* \return time (in microseconds) the display of subtitles is being delayed
* \version LibVLC 2.0.0 or later
*/
LIBVLC_API int64_t libvlc_video_get_spu_delay( libvlc_media_player_t *p_mi );
/**
* Set the subtitle delay. This affects the timing of when the subtitle will
* be displayed. Positive values result in subtitles being displayed later,
* while negative values will result in subtitles being displayed earlier.
*
* The subtitle delay will be reset to zero each time the media changes.
*
* \param p_mi media player
* \param i_delay time (in microseconds) the display of subtitles should be delayed
* \return 0 on success, -1 on error
* \version LibVLC 2.0.0 or later
*/
LIBVLC_API int libvlc_video_set_spu_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
/**
* Get the description of available titles.
*
* \param p_mi the media player
* \return list containing description of available titles
*/
LIBVLC_API libvlc_track_description_t *
libvlc_video_get_title_description( libvlc_media_player_t *p_mi );
/**
* Get the description of available chapters for specific title.
*
* \param p_mi the media player
* \param i_title selected title
* \return list containing description of available chapter for title i_title
*/
LIBVLC_API libvlc_track_description_t *
libvlc_video_get_chapter_description( libvlc_media_player_t *p_mi, int i_title );
/**
* Get current crop filter geometry.
*
* \param p_mi the media player
* \return the crop filter geometry or NULL if unset
*/
LIBVLC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *p_mi );
/**
* Set new crop filter geometry.
*
* \param p_mi the media player
* \param psz_geometry new crop filter geometry (NULL to unset)
*/
LIBVLC_API
void libvlc_video_set_crop_geometry( libvlc_media_player_t *p_mi, const char *psz_geometry );
/**
* Get current teletext page requested.
*
* \param p_mi the media player
* \return the current teletext page requested.
*/
LIBVLC_API int libvlc_video_get_teletext( libvlc_media_player_t *p_mi );
/**
* Set new teletext page to retrieve.
*
* \param p_mi the media player
* \param i_page teletex page number requested
*/
LIBVLC_API void libvlc_video_set_teletext( libvlc_media_player_t *p_mi, int i_page );
/**
* Toggle teletext transparent status on video output.
*
* \param p_mi the media player
*/
LIBVLC_API void libvlc_toggle_teletext( libvlc_media_player_t *p_mi );
/**
* Get number of available video tracks.
*
* \param p_mi media player
* \return the number of available video tracks (int)
*/
LIBVLC_API int libvlc_video_get_track_count( libvlc_media_player_t *p_mi );
/**
* Get the description of available video tracks.
*
* \param p_mi media player
* \return list with description of available video tracks, or NULL on error
*/
LIBVLC_API libvlc_track_description_t *
libvlc_video_get_track_description( libvlc_media_player_t *p_mi );
/**
* Get current video track.
*
* \param p_mi media player
* \return the video track ID (int) or -1 if no active input
*/
LIBVLC_API int libvlc_video_get_track( libvlc_media_player_t *p_mi );
/**
* Set video track.
*
* \param p_mi media player
* \param i_track the track ID (i_id field from track description)
* \return 0 on success, -1 if out of range
*/
LIBVLC_API
int libvlc_video_set_track( libvlc_media_player_t *p_mi, int i_track );
/**
* Take a snapshot of the current video window.
*
* If i_width AND i_height is 0, original size is used.
* If i_width XOR i_height is 0, original aspect-ratio is preserved.
*
* \param p_mi media player instance
* \param num number of video output (typically 0 for the first/only one)
* \param psz_filepath the path where to save the screenshot to
* \param i_width the snapshot's width
* \param i_height the snapshot's height
* \return 0 on success, -1 if the video was not found
*/
LIBVLC_API
int libvlc_video_take_snapshot( libvlc_media_player_t *p_mi, unsigned num,
const char *psz_filepath, unsigned int i_width,
unsigned int i_height );
/**
* Enable or disable deinterlace filter
*
* \param p_mi libvlc media player
* \param psz_mode type of deinterlace filter, NULL to disable
*/
LIBVLC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *p_mi,
const char *psz_mode );
/**
* Get an integer marquee option value
*
* \param p_mi libvlc media player
* \param option marq option to get \see libvlc_video_marquee_int_option_t
*/
LIBVLC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *p_mi,
unsigned option );
/**
* Get a string marquee option value
*
* \param p_mi libvlc media player
* \param option marq option to get \see libvlc_video_marquee_string_option_t
*/
LIBVLC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *p_mi,
unsigned option );
/**
* Enable, disable or set an integer marquee option
*
* Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
* or disabling (arg 0) the marq filter.
*
* \param p_mi libvlc media player
* \param option marq option to set \see libvlc_video_marquee_int_option_t
* \param i_val marq option value
*/
LIBVLC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *p_mi,
unsigned option, int i_val );
/**
* Set a marquee string option
*
* \param p_mi libvlc media player
* \param option marq option to set \see libvlc_video_marquee_string_option_t
* \param psz_text marq option value
*/
LIBVLC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *p_mi,
unsigned option, const char *psz_text );
/** option values for libvlc_video_{get,set}_logo_{int,string} */
enum libvlc_video_logo_option_t {
libvlc_logo_enable,
libvlc_logo_file, /**< string argument, "file,d,t;file,d,t;..." */
libvlc_logo_x,
libvlc_logo_y,
libvlc_logo_delay,
libvlc_logo_repeat,
libvlc_logo_opacity,
libvlc_logo_position
};
/**
* Get integer logo option.
*
* \param p_mi libvlc media player instance
* \param option logo option to get, values of libvlc_video_logo_option_t
*/
LIBVLC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi,
unsigned option );
/**
* Set logo option as integer. Options that take a different type value
* are ignored.
* Passing libvlc_logo_enable as option value has the side effect of
* starting (arg !0) or stopping (arg 0) the logo filter.
*
* \param p_mi libvlc media player instance
* \param option logo option to set, values of libvlc_video_logo_option_t
* \param value logo option value
*/
LIBVLC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi,
unsigned option, int value );
/**
* Set logo option as string. Options that take a different type value
* are ignored.
*
* \param p_mi libvlc media player instance
* \param option logo option to set, values of libvlc_video_logo_option_t
* \param psz_value logo option value
*/
LIBVLC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
unsigned option, const char *psz_value );
/** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */
enum libvlc_video_adjust_option_t {
libvlc_adjust_Enable = 0,
libvlc_adjust_Contrast,
libvlc_adjust_Brightness,
libvlc_adjust_Hue,
libvlc_adjust_Saturation,
libvlc_adjust_Gamma
};
/**
* Get integer adjust option.
*
* \param p_mi libvlc media player instance
* \param option adjust option to get, values of libvlc_video_adjust_option_t
* \version LibVLC 1.1.1 and later.
*/
LIBVLC_API int libvlc_video_get_adjust_int( libvlc_media_player_t *p_mi,
unsigned option );
/**
* Set adjust option as integer. Options that take a different type value
* are ignored.
* Passing libvlc_adjust_enable as option value has the side effect of
* starting (arg !0) or stopping (arg 0) the adjust filter.
*
* \param p_mi libvlc media player instance
* \param option adust option to set, values of libvlc_video_adjust_option_t
* \param value adjust option value
* \version LibVLC 1.1.1 and later.
*/
LIBVLC_API void libvlc_video_set_adjust_int( libvlc_media_player_t *p_mi,
unsigned option, int value );
/**
* Get float adjust option.
*
* \param p_mi libvlc media player instance
* \param option adjust option to get, values of libvlc_video_adjust_option_t
* \version LibVLC 1.1.1 and later.
*/
LIBVLC_API float libvlc_video_get_adjust_float( libvlc_media_player_t *p_mi,
unsigned option );
/**
* Set adjust option as float. Options that take a different type value
* are ignored.
*
* \param p_mi libvlc media player instance
* \param option adust option to set, values of libvlc_video_adjust_option_t
* \param value adjust option value
* \version LibVLC 1.1.1 and later.
*/
LIBVLC_API void libvlc_video_set_adjust_float( libvlc_media_player_t *p_mi,
unsigned option, float value );
/** @} video */
/** \defgroup libvlc_audio LibVLC audio controls
* @{
*/
/**
* Audio device types
*/
typedef enum libvlc_audio_output_device_types_t {
libvlc_AudioOutputDevice_Error = -1,
libvlc_AudioOutputDevice_Mono = 1,
libvlc_AudioOutputDevice_Stereo = 2,
libvlc_AudioOutputDevice_2F2R = 4,
libvlc_AudioOutputDevice_3F2R = 5,
libvlc_AudioOutputDevice_5_1 = 6,
libvlc_AudioOutputDevice_6_1 = 7,
libvlc_AudioOutputDevice_7_1 = 8,
libvlc_AudioOutputDevice_SPDIF = 10
} libvlc_audio_output_device_types_t;
/**
* Audio channels
*/
typedef enum libvlc_audio_output_channel_t {
libvlc_AudioChannel_Error = -1,
libvlc_AudioChannel_Stereo = 1,
libvlc_AudioChannel_RStereo = 2,
libvlc_AudioChannel_Left = 3,
libvlc_AudioChannel_Right = 4,
libvlc_AudioChannel_Dolbys = 5
} libvlc_audio_output_channel_t;
/**
* Gets the list of available audio outputs
*
* \param p_instance libvlc instance
* \return list of available audio outputs. It must be freed it with
* \see libvlc_audio_output_list_release \see libvlc_audio_output_t .
* In case of error, NULL is returned.
*/
LIBVLC_API libvlc_audio_output_t *
libvlc_audio_output_list_get( libvlc_instance_t *p_instance );
/**
* Frees the list of available audio outputs
*
* \param p_list list with audio outputs for release
*/
LIBVLC_API
void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list );
/**
* Sets the audio output.
* \note Any change will take be effect only after playback is stopped and
* restarted. Audio output cannot be changed while playing.
*
* \param p_mi media player
* \param psz_name name of audio output,
* use psz_name of \see libvlc_audio_output_t
* \return 0 if function succeded, -1 on error
*/
LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi,
const char *psz_name );
/**
* Backward compatibility stub. Do not use in new code.
* Use libvlc_audio_output_device_list_get() instead.
* \return always 0.
*/
LIBVLC_DEPRECATED LIBVLC_API
int libvlc_audio_output_device_count( libvlc_instance_t *, const char * );
/**
* Backward compatibility stub. Do not use in new code.
* Use libvlc_audio_output_device_list_get() instead.
* \return always NULL.
*/
LIBVLC_DEPRECATED LIBVLC_API
char *libvlc_audio_output_device_longname( libvlc_instance_t *, const char *,
int );
/**
* Backward compatibility stub. Do not use in new code.
* Use libvlc_audio_output_device_list_get() instead.
* \return always NULL.
*/
LIBVLC_DEPRECATED LIBVLC_API
char *libvlc_audio_output_device_id( libvlc_instance_t *, const char *, int );
/**
* Gets a list of audio output devices for a given audio output.
* \see libvlc_audio_output_device_set().
*
* \note Not all audio outputs support this. In particular, an empty (NULL)
* list of devices does <b>not</b> imply that the specified audio output does
* not work.
*
* \note The list might not be exhaustive.
*
* \warning Some audio output devices in the list might not actually work in
* some circumstances. By default, it is recommended to not specify any
* explicit audio device.
*
* \param p_instance libvlc instance
* \param psz_aout audio output name
* (as returned by libvlc_audio_output_list_get())
* \return A NULL-terminated linked list of potential audio output devices.
* It must be freed it with libvlc_audio_output_device_list_release()
* \version LibVLC 2.1.0 or later.
*/
LIBVLC_API libvlc_audio_output_device_t *
libvlc_audio_output_device_list_get( libvlc_instance_t *p_instance,
const char *aout );
/**
* Frees a list of available audio output devices.
*
* \param p_list list with audio outputs for release
* \version LibVLC 2.1.0 or later.
*/
LIBVLC_API void libvlc_audio_output_device_list_release(
libvlc_audio_output_device_t *p_list );
/**
* Configures an explicit audio output device for a given audio output plugin.
* A list of possible devices can be obtained with
* libvlc_audio_output_device_list_get().
*
* \note This function does not select the specified audio output plugin.
* libvlc_audio_output_set() is used for that purpose.
*
* \warning The syntax for the device parameter depends on the audio output.
* This is not portable. Only use this function if you know what you are doing.
* Some audio outputs do not support this function (e.g. PulseAudio, WASAPI).
* Some audio outputs require further parameters (e.g. ALSA: channels map).
*
* \param p_mi media player
* \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
* \param psz_device_id device
* \return Nothing. Errors are ignored.
*/
LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *p_mi,
const char *psz_audio_output,
const char *psz_device_id );
/**
* Stub for backward compatibility.
* \return always -1.
*/
LIBVLC_DEPRECATED
LIBVLC_API int libvlc_audio_output_get_device_type( libvlc_media_player_t *p_mi );
/**
* Stub for backward compatibility.
*/
LIBVLC_DEPRECATED
LIBVLC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *,
int );
/**
* Toggle mute status.
*
* \param p_mi media player
* \warning Toggling mute atomically is not always possible: On some platforms,
* other processes can mute the VLC audio playback stream asynchronously. Thus,
* there is a small race condition where toggling will not work.
* See also the limitations of libvlc_audio_set_mute().
*/
LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi );
/**
* Get current mute status.
*
* \param p_mi media player
* \return the mute status (boolean) if defined, -1 if undefined/unapplicable
*/
LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi );
/**
* Set mute status.
*
* \param p_mi media player
* \param status If status is true then mute, otherwise unmute
* \warning This function does not always work. If there are no active audio
* playback stream, the mute status might not be available. If digital
* pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also
* some audio output plugins do not support muting at all.
* \note To force silent playback, disable all audio tracks. This is more
* efficient and reliable than mute.
*/
LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status );
/**
* Get current software audio volume.
*
* \param p_mi media player
* \return the software volume in percents
* (0 = mute, 100 = nominal / 0dB)
*/
LIBVLC_API int libvlc_audio_get_volume( libvlc_media_player_t *p_mi );
/**
* Set current software audio volume.
*
* \param p_mi media player
* \param i_volume the volume in percents (0 = mute, 100 = 0dB)
* \return 0 if the volume was set, -1 if it was out of range
*/
LIBVLC_API int libvlc_audio_set_volume( libvlc_media_player_t *p_mi, int i_volume );
/**
* Get number of available audio tracks.
*
* \param p_mi media player
* \return the number of available audio tracks (int), or -1 if unavailable
*/
LIBVLC_API int libvlc_audio_get_track_count( libvlc_media_player_t *p_mi );
/**
* Get the description of available audio tracks.
*
* \param p_mi media player
* \return list with description of available audio tracks, or NULL
*/
LIBVLC_API libvlc_track_description_t *
libvlc_audio_get_track_description( libvlc_media_player_t *p_mi );
/**
* Get current audio track.
*
* \param p_mi media player
* \return the audio track ID or -1 if no active input.
*/
LIBVLC_API int libvlc_audio_get_track( libvlc_media_player_t *p_mi );
/**
* Set current audio track.
*
* \param p_mi media player
* \param i_track the track ID (i_id field from track description)
* \return 0 on success, -1 on error
*/
LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track );
/**
* Get current audio channel.
*
* \param p_mi media player
* \return the audio channel \see libvlc_audio_output_channel_t
*/
LIBVLC_API int libvlc_audio_get_channel( libvlc_media_player_t *p_mi );
/**
* Set current audio channel.
*
* \param p_mi media player
* \param channel the audio channel, \see libvlc_audio_output_channel_t
* \return 0 on success, -1 on error
*/
LIBVLC_API int libvlc_audio_set_channel( libvlc_media_player_t *p_mi, int channel );
/**
* Get current audio delay.
*
* \param p_mi media player
* \return the audio delay (microseconds)
* \version LibVLC 1.1.1 or later
*/
LIBVLC_API int64_t libvlc_audio_get_delay( libvlc_media_player_t *p_mi );
/**
* Set current audio delay. The audio delay will be reset to zero each time the media changes.
*
* \param p_mi media player
* \param i_delay the audio delay (microseconds)
* \return 0 on success, -1 on error
* \version LibVLC 1.1.1 or later
*/
LIBVLC_API int libvlc_audio_set_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
/** @} audio */
/** @} media_player */
# ifdef __cplusplus
}
# endif
#endif /* VLC_LIBVLC_MEDIA_PLAYER_H */
|