1 /***************************************************************** 2 * gmerlin - a general purpose multimedia framework and applications 3 * 4 * Copyright (c) 2001 - 2011 Members of the Gmerlin project 5 * gmerlin-general@lists.sourceforge.net 6 * http://gmerlin.sourceforge.net 7 * 8 * This program is free software: you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License as published by 10 * the Free Software Foundation, either version 2 of the License, or 11 * (at your option) any later version. 12 * 13 * This program is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * GNU General Public License for more details. 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with this program. If not, see <http://www.gnu.org/licenses/>. 20 * *****************************************************************/ 21 22 #ifndef __BG_PLUGIN_H_ 23 #define __BG_PLUGIN_H_ 24 25 #include <gavl/gavl.h> 26 #include <gavl/compression.h> 27 #include <gmerlin/parameter.h> 28 #include <gmerlin/streaminfo.h> 29 #include <gmerlin/accelerator.h> 30 #include <gmerlin/edl.h> 31 32 /** \defgroup plugin Plugins 33 * \brief Plugin types and associated functions 34 * 35 * Gmerlin plugins are structs which contain function pointers and 36 * other data. The API looks a bit complicated, but many functions are 37 * optional, so plugins can, in prinpiple, be very simple. 38 * All plugins are based on a common struct (\ref bg_plugin_common_t), 39 * which contains an identifier for the plugin type. The bg_plugin_common_t 40 * pointer can be casted to the derived plugin types. 41 * 42 * The application calls the functions in the order, in which they are 43 * defined. Some functions are mandatory from the plugin view (i.e. they 44 * must be non-null), some functions are mandatory for the application 45 * (i.e. the application must check for them and call them if they are 46 * present. 47 * 48 * The configuration of the plugins works entirely through the 49 * parameter passing mechanisms (see \ref parameter). Configurable 50 * plugins only need to define get_parameters and set_parameter methods. 51 * Encoding plugins have an additional layer, which allows setting 52 * parameters individually for each stream. 53 * 54 * Events, which are caught by the plugins (e.g. song name changes or 55 * mouse clicks) are propagated through optional callbacks. 56 * These are passed from the application to the plugin with the 57 * set_callbacks function. 58 * Applications should not rely on any callback to be actually supported by 59 * a plugin. Plugins should not rely on the presence of any callback 60 */ 61 62 63 /** \ingroup plugin 64 * \brief Generic prototype for reading audio 65 * \param priv Private data 66 * \param frame Audio frame 67 * \param stream Stream index (0 is only one stream) 68 * \param samples Samples to read 69 * \returns The number of samples read 70 * 71 * This is a generic prototype for reading audio. It's shared between 72 * input pluigns, recorders and filters to enable arbitrary chaining. 73 */ 74 75 typedef int (*bg_read_audio_func_t)(void * priv, gavl_audio_frame_t* frame, 76 int stream, 77 int num_samples); 78 79 /** \ingroup plugin 80 * \brief Generic prototype for reading video 81 * \param priv Private data 82 * \param frame Video frame 83 * \param stream Stream index (0 is only one stream) 84 * \returns 1 if a frame could be read, 0 else 85 * 86 * This is a generic prototype for reading audio. It's shared between 87 * input pluigns, recorders and filters to enable arbitrary chaining. 88 */ 89 90 typedef int (*bg_read_video_func_t)(void * priv, gavl_video_frame_t* frame, 91 int stream); 92 93 /** \defgroup plugin_flags Plugin flags 94 * \ingroup plugin 95 * \brief Macros for the plugin flags 96 * 97 * 98 * All plugins must have at least one flag set. 99 * @{ 100 */ 101 102 #define BG_PLUGIN_REMOVABLE (1<<0) //!< Plugin handles removable media (CD, DVD etc.) 103 #define BG_PLUGIN_FILE (1<<1) //!< Plugin reads/writes files 104 #define BG_PLUGIN_RECORDER (1<<2) //!< Plugin does hardware recording 105 #define BG_PLUGIN_URL (1<<3) //!< Plugin can load URLs 106 #define BG_PLUGIN_PLAYBACK (1<<4) //!< Plugin is an audio or video driver for playback 107 #define BG_PLUGIN_STDIN (1<<8) //!< Plugin can read from stdin ("-") 108 #define BG_PLUGIN_TUNER (1<<9) //!< Plugin has some kind of tuner. Channels will be loaded as tracks. 109 #define BG_PLUGIN_FILTER_1 (1<<10) //!< Plugin acts as a filter with one input 110 #define BG_PLUGIN_EMBED_WINDOW (1<<11) //!< Plugin can embed it's window into another application 111 #define BG_PLUGIN_VISUALIZE_FRAME (1<<12) //!< Visualization plugin outputs video frames 112 #define BG_PLUGIN_VISUALIZE_GL (1<<13) //!< Visualization plugin outputs via OpenGL 113 #define BG_PLUGIN_PP (1<<14) //!< Postprocessor 114 #define BG_PLUGIN_CALLBACKS (1<<15) //!< Plugin can be opened from callbacks 115 #define BG_PLUGIN_BROADCAST (1<<16) //!< Plugin can broadcasts (e.g. webstreams) 116 #define BG_PLUGIN_DEVPARAM (1<<17) //!< Plugin has pluggable devices as parameters, which must be updated regurarly 117 118 #define BG_PLUGIN_UNSUPPORTED (1<<24) //!< Plugin is not supported. Only for a foreign API plugins 119 120 121 #define BG_PLUGIN_ALL 0xFFFFFFFF //!< Mask of all possible plugin flags 122 123 /** @} 124 */ 125 126 #define BG_PLUGIN_API_VERSION 26 127 128 /* Include this into all plugin modules exactly once 129 to let the plugin loader obtain the API version */ 130 131 #define BG_GET_PLUGIN_API_VERSION \ 132 int get_plugin_api_version() __attribute__ ((visibility("default"))); \ 133 int get_plugin_api_version() { return BG_PLUGIN_API_VERSION; } 134 135 #define BG_PLUGIN_PRIORITY_MIN 1 136 #define BG_PLUGIN_PRIORITY_MAX 10 137 138 /** \defgroup plugin_i Media input 139 * \ingroup plugin 140 * \brief Media input 141 */ 142 143 /** \ingroup plugin_i 144 * \brief Stream actions 145 * 146 * These describe how streams should be handled by the input 147 * plugin. Note that by default, each stream is switched off. 148 */ 149 150 typedef enum 151 { 152 BG_STREAM_ACTION_OFF = 0, //!< Stream is switched off and will be ignored 153 BG_STREAM_ACTION_DECODE, //!< Stream is switched on and will be decoded 154 BG_STREAM_ACTION_READRAW, //!< Stream will be read in compressed form 155 156 } bg_stream_action_t; 157 158 /*************************************************** 159 * Plugin API 160 * 161 * Plugin dlls contain a symbol "the_plugin", 162 * which points to one of the structures below. 163 * The member functions are described below. 164 * 165 ***************************************************/ 166 167 /* 168 * Plugin types 169 */ 170 171 /** \ingroup plugin 172 * \brief Plugin types 173 */ 174 175 typedef enum 176 { 177 BG_PLUGIN_NONE = 0, //!< None or undefined 178 BG_PLUGIN_INPUT = (1<<0), //!< Media input 179 BG_PLUGIN_OUTPUT_AUDIO = (1<<1), //!< Audio output 180 BG_PLUGIN_OUTPUT_VIDEO = (1<<2), //!< Video output 181 BG_PLUGIN_RECORDER_AUDIO = (1<<3), //!< Audio recorder 182 BG_PLUGIN_RECORDER_VIDEO = (1<<4), //!< Video recorder 183 BG_PLUGIN_ENCODER_AUDIO = (1<<5), //!< Encoder for audio only 184 BG_PLUGIN_ENCODER_VIDEO = (1<<6), //!< Encoder for video only 185 BG_PLUGIN_ENCODER_SUBTITLE_TEXT = (1<<7), //!< Encoder for text subtitles only 186 BG_PLUGIN_ENCODER_SUBTITLE_OVERLAY = (1<<8), //!< Encoder for overlay subtitles only 187 BG_PLUGIN_ENCODER = (1<<9), //!< Encoder for multiple kinds of streams 188 BG_PLUGIN_ENCODER_PP = (1<<10),//!< Encoder postprocessor (e.g. CD burner) 189 BG_PLUGIN_IMAGE_READER = (1<<11),//!< Image reader 190 BG_PLUGIN_IMAGE_WRITER = (1<<12), //!< Image writer 191 BG_PLUGIN_FILTER_AUDIO = (1<<13), //!< Audio filter 192 BG_PLUGIN_FILTER_VIDEO = (1<<14), //!< Video filter 193 BG_PLUGIN_VISUALIZATION = (1<<15), //!< Visualization 194 BG_PLUGIN_AV_RECORDER = (1<<16), //!< Audio/Video recorder 195 } bg_plugin_type_t; 196 197 /** \ingroup plugin 198 * \brief Device description 199 * 200 * The find_devices() function of a plugin returns 201 * a NULL terminated array of devices. It's used mainly for input plugins, 202 * which access multiple drives. For output plugins, devices are normal parameters. 203 */ 204 205 typedef struct 206 { 207 char * device; //!< String, which can be passed to the open() method 208 char * name; //!< More humanized description, might be NULL 209 } bg_device_info_t; 210 211 /** \ingroup plugin 212 * \brief Append device info to an existing array and return the new array. 213 * \param arr An array (can be NULL) 214 * \param device Device string 215 * \param name Humanized description (can be NULL) 216 * \returns Newly allocated array. The source array is freed. 217 * 218 * This is used mainly by the device detection routines of the plugins 219 */ 220 221 bg_device_info_t * bg_device_info_append(bg_device_info_t * arr, 222 const char * device, 223 const char * name); 224 225 /** \ingroup plugin 226 * \brief Free an array of device descriptions 227 * \param arr a device array 228 */ 229 230 void bg_device_info_destroy(bg_device_info_t * arr); 231 232 /* Common part */ 233 234 /** \ingroup plugin 235 * \brief Typedef for base structure common to all plugins 236 */ 237 238 typedef struct bg_plugin_common_s bg_plugin_common_t; 239 240 /** \ingroup plugin 241 * \brief Base structure common to all plugins 242 */ 243 244 struct bg_plugin_common_s 245 { 246 char * gettext_domain; //!< First argument for bindtextdomain(). 247 char * gettext_directory; //!< Second argument for bindtextdomain(). 248 249 char * name; //!< Unique short name 250 char * long_name; //!< Humanized name for GUI widgets 251 bg_plugin_type_t type; //!< Type 252 int flags; //!< Flags (see defines) 253 254 char * description; //!< Textual description 255 256 /* 257 * If there might be more than one plugin for the same 258 * job, there is a priority (0..10) which is used for the 259 * decision 260 */ 261 262 int priority; //!< Priority (between 1 and 10). 263 264 /** \brief Create the instance, return handle. 265 * \returns A private handle, which is the first argument to all subsequent functions. 266 */ 267 268 void * (*create)(); 269 270 /** \brief Destroy plugin instance 271 * \param priv The handle returned by the create() method 272 * 273 * Destroy everything, making it ready for dlclose() 274 * This function might also be called on opened plugins, 275 * so the plugins should call their close()-function from 276 * within the destroy method. 277 */ 278 279 void (*destroy)(void* priv); 280 281 /** \brief Get available parameters 282 * \param priv The handle returned by the create() method 283 * \returns a NULL terminated parameter array. 284 * 285 * The returned array is owned (an should be freed) by the plugin. 286 */ 287 288 const bg_parameter_info_t * (*get_parameters)(void * priv); 289 290 /** \brief Set configuration parameter (optional) 291 */ 292 293 bg_set_parameter_func_t set_parameter; 294 295 /** \brief Get configuration parameter (optional) 296 * 297 * This must only return parameters, which are changed internally 298 * by the plugins. 299 */ 300 301 bg_get_parameter_func_t get_parameter; 302 303 /** \brief Check, if a device can be opened by the plugin (optional) 304 * \param device The device as passed to the open() method 305 * \param name Returns the name if available 306 * \returns 1 if the device is supported, 0 else 307 * 308 * The name should be set to NULL before this call, and must be freed 309 * if it's non-NULL after the call. 310 */ 311 312 int (*check_device)(const char * device, char ** name); 313 314 315 /** \brief Get an array of all supported devices found on the system 316 * \returns A NULL terminated device array 317 * 318 * The returned array must be freed with \ref bg_device_info_destroy by 319 * the caller. 320 */ 321 322 bg_device_info_t * (*find_devices)(); 323 324 }; 325 326 /* 327 * Plugin callbacks: Functions called by the 328 * plugin to reflect user input or other changes 329 * Applications might pass NULL callbacks, 330 * so plugins MUST check for valid callbacks structure 331 * before calling any of these functions 332 */ 333 334 /* Input plugin */ 335 336 /** \ingroup plugin_i 337 * \brief typedef for input callbacks 338 * 339 */ 340 341 typedef struct bg_input_callbacks_s bg_input_callbacks_t; 342 343 /** \ingroup plugin_i 344 * \brief Callbacks for input plugins 345 * 346 * Passing the callback structure to the plugin is optional. Futhermore, 347 * any of the callback functions is optional (i.e. can be NULL). The plugin 348 * might use the callbacks for propagating events. 349 */ 350 351 struct bg_input_callbacks_s 352 { 353 /** \brief Duration changed 354 * \param data The data member of this bg_input_callbacks_s struct 355 * \param time The new duration 356 */ 357 358 void (*duration_changed)(void * data, gavl_time_t duration); 359 360 /** \brief Name changed 361 * \param data The data member of this bg_input_callbacks_s struct 362 * \param time The new name 363 * 364 * This is for web-radio stations, which send song-names. 365 */ 366 367 void (*name_changed)(void * data, const char * name); 368 369 /** \brief Metadata changed 370 * \param data The data member of this bg_input_callbacks_s struct 371 * \param m The new metadata 372 * 373 * This is for web-radio stations, which send metadata for each song. 374 */ 375 376 void (*metadata_changed)(void * data, const gavl_metadata_t * m); 377 378 /** \brief Buffer callback 379 * \param data The data member of this bg_input_callbacks_s struct 380 * \param percentage The buffer fullness (0.0..1.0) 381 * 382 * For network connections, plugins might buffer data. This takes some time, 383 * so they notify the API about the progress with this callback. 384 */ 385 386 void (*buffer_notify)(void * data, float percentage); 387 388 /** \brief Authentication callback 389 * \param data The data member of this bg_input_callbacks_s struct 390 * \param resource Name of the resource (e.g. server name) 391 * \param username Returns the username 392 * \param password Returns the password 393 * \returns 1 if username and password are available, 0 else. 394 * 395 * For sources, which require authentication (like FTP servers), this 396 * function is called by the plugin to get username and password. 397 * Username and password must be returned in newly allocated strings, which 398 * will be freed by the plugin. 399 */ 400 401 int (*user_pass)(void * data, const char * resource, 402 char ** username, char ** password); 403 404 /** \brief Aspect ratio change callback 405 * \param data The data member of this bg_input_callbacks_s struct 406 * \param stream Video stream index (starts with 0) 407 * \param pixel_width New pixel width 408 * \param pixel_height New pixel height 409 * 410 * Some streams (e.g. DVB) change the pixel aspect ratio on the fly. 411 * If the input plugin detects such a change, it should call this 412 * callback. 413 */ 414 415 void (*aspect_changed)(void * data, int stream, 416 int pixel_width, int pixel_height); 417 418 419 void * data; //!< Application specific data passed as the first argument to all callbacks. 420 421 }; 422 423 /************************************************* 424 * MEDIA INPUT 425 *************************************************/ 426 427 /** \ingroup plugin_i 428 * \brief Typedef for input plugin 429 */ 430 431 typedef struct bg_input_plugin_s bg_input_plugin_t; 432 433 434 /** \ingroup plugin_i 435 * \brief Input plugin 436 * 437 * This is for all kinds of media inputs (files, disks, urls, etc), except recording from 438 * hardware devices (see \ref plugin_r). 439 * 440 * 441 */ 442 443 struct bg_input_plugin_s 444 { 445 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 446 447 /** \brief Get supported protocols 448 * \param priv The handle returned by the create() method 449 * \returns A space separated list of protocols 450 */ 451 452 const char * (*get_protocols)(void * priv); 453 /** \brief Get supported mimetypes 454 * \param priv The handle returned by the create() method 455 * \returns A space separated list of mimetypes 456 */ 457 const char * (*get_mimetypes)(void * priv); 458 459 /** \brief Get supported extensions 460 * \param priv The handle returned by the create() method 461 * \returns A space separated list of extensions 462 */ 463 const char * (*get_extensions)(void * priv); 464 465 /** \brief Set callbacks 466 * \param priv The handle returned by the create() method 467 * \param callbacks Callback structure initialized by the caller before 468 * 469 * Set callback functions, which will be called by the plugin. 470 * Defining as well as calling this function is optional. Any of the 471 * members of callbacks can be NULL. 472 */ 473 474 void (*set_callbacks)(void * priv, bg_input_callbacks_t * callbacks); 475 476 /** \brief Open file/url/device 477 * \param priv The handle returned by the create() method 478 * \param arg Filename, URL or device name 479 * \returns 1 on success, 0 on failure 480 */ 481 int (*open)(void * priv, const char * arg); 482 483 /** \brief Open plugin from filedescriptor (optional) 484 * \param priv The handle returned by the create() method 485 * \param fd Open filedescriptor 486 * \param total_bytes Totally available bytes or 0 if unknown 487 * \param mimetype Mimetype from http header (or NULL) 488 * \returns 1 on success, 0 on failure 489 */ 490 491 int (*open_fd)(void * priv, int fd, int64_t total_bytes, 492 const char * mimetype); 493 494 /** \brief Open plugin with callbacks (optional) 495 * \param priv The handle returned by the create() method 496 * \param read_callback Callback for reading data 497 * \param seek_callback Callback for seeking 498 * \param cb_priv Private argument for the callbacks 499 * \param filename The filename of the input or NULL if this info is not known. 500 * \param mimetype The mimetype of the input or NULL if this info is not known. 501 * \param total_bytes total number of bytes or 0 if this info is not known. 502 * \returns 1 on success, 0 on failure 503 */ 504 505 int (*open_callbacks)(void * priv, 506 int (*read_callback)(void * priv, uint8_t * data, int len), 507 int64_t (*seek_callback)(void * priv, uint64_t pos, int whence), 508 void * cb_priv, const char * filename, const char * mimetype, 509 int64_t total_bytes); 510 511 /** \brief Get the edl (optional) 512 * \param priv The handle returned by the create() method 513 * \returns The edl if any 514 */ 515 516 const bg_edl_t * (*get_edl)(void * priv); 517 518 /** \brief Get the disc name (optional) 519 * \param priv The handle returned by the create() method 520 * \returns The name of the disc if any 521 * 522 * This is only for plugins, which access removable discs (e.g. CDs). 523 */ 524 525 const char * (*get_disc_name)(void * priv); 526 527 /** \brief Eject disc (optional) 528 * \param priv The handle returned by the create() method 529 * \returns 1 if eject was successful 530 * 531 * This is only for plugins, which access removable discs (e.g. CDs). 532 * \todo This function doesn't work reliably now. Either fix or remove this 533 */ 534 535 int (*eject_disc)(const char * device); 536 537 /** \brief Get the number of tracks 538 * \param priv The handle returned by the create() method 539 * \returns The number of tracks 540 * 541 * This can be NULL for plugins, which support just one track. 542 */ 543 544 int (*get_num_tracks)(void * priv); 545 546 /** \brief Return information about a track 547 * \param priv The handle returned by the create() method 548 * \param track Track index starting with 0 549 * \returns The track info 550 * 551 * The following fields MUST be valid after this call: 552 * - num_audio_streams 553 * - num_video_streams 554 * - num_subtitle_streams 555 * - duration 556 * - Name (If NULL, the filename minus the suffix will be used) 557 * 558 * Other data, especially audio and video formats, will become valid after the 559 * start() call (see below). 560 */ 561 562 bg_track_info_t * (*get_track_info)(void * priv, int track); 563 564 /** \brief Set the track to be played 565 * \param priv The handle returned by the create() method 566 * \param track Track index starting with 0 567 * 568 * This has to be defined even if the plugin doesn't support 569 * multiple tracks. In addition to selecting the track, 570 * the plugin should also reset it's internal state such 571 * that streams can newly be selected. 572 */ 573 574 int (*set_track)(void * priv, int track); 575 576 /** \brief Get the compression info of an audio stream 577 * \param priv The handle returned by the create() method 578 * \param stream Stream index starting with 0 579 * \param info Returns the compression info 580 * \returns 1 if the compression info was returned, 0 if the stream cannot be output in compressed form 581 * 582 * The returned compression info should be freed with 583 * \ref gavl_compression_info_free 584 */ 585 586 int (*get_audio_compression_info)(void * priv, int stream, 587 gavl_compression_info_t * info); 588 589 /** \brief Get the compression info of a video stream 590 * \param priv The handle returned by the create() method 591 * \param stream Stream index starting with 0 592 * \param info Returns the compression info 593 * \returns 1 if the compression info was returned, 0 if the stream cannot be output in compressed form 594 * 595 * The returned compression info should be freed with 596 * \ref gavl_compression_info_free 597 */ 598 599 int (*get_video_compression_info)(void * priv, int stream, 600 gavl_compression_info_t * info); 601 602 /* 603 * These functions set the audio- video- and subpicture streams 604 * as well as programs (== DVD Angles). All these start with 0 605 * 606 * Arguments for actions are defined in the enum bg_stream_action_t 607 * above. Plugins must return FALSE on failure (e.g. no such stream) 608 * 609 * Functions must be defined only, if the corresponding stream 610 * type is supported by the plugin and can be switched. 611 * Single stream plugins can leave these NULL 612 * Gmerlin will never try to call these functions on nonexistent streams 613 */ 614 615 /** \brief Setup audio stream 616 * \param priv The handle returned by the create() method 617 * \param stream Stream index starting with 0 618 * \param action What to do with the stream 619 * \returns 1 on success, 0 on failure 620 */ 621 622 int (*set_audio_stream)(void * priv, int stream, bg_stream_action_t action); 623 624 /** \brief Setup video stream 625 * \param priv The handle returned by the create() method 626 * \param stream Stream index starting with 0 627 * \param action What to do with the stream 628 * \returns 1 on success, 0 on failure 629 */ 630 631 int (*set_video_stream)(void * priv, int stream, bg_stream_action_t action); 632 633 /** \brief Setup subtitle stream 634 * \param priv The handle returned by the create() method 635 * \param stream Stream index starting with 0 636 * \param action What to do with the stream 637 * \returns 1 on success, 0 on failure 638 */ 639 640 int (*set_subtitle_stream)(void * priv, int stream, bg_stream_action_t action); 641 642 /** \brief Start decoding 643 * \param priv The handle returned by the create() method 644 * \returns 1 on success, 0 on error 645 * 646 * After this call, all remaining members of the track info returned earlier 647 * (especially audio- and video formats) must be valid. 648 * 649 * From the plugins point of view, this is the last chance to return 0 650 * if something fails 651 */ 652 653 int (*start)(void * priv); 654 655 /** \brief Get frame table 656 * \param priv The handle returned by the create() method 657 * \param stream Stream index (starting with 0) 658 * \returns A newly allocated frame table or NULL 659 * 660 * The returned frame table must be freed with 661 * \ref gavl_frame_table_destroy. 662 */ 663 664 gavl_frame_table_t * (*get_frame_table)(void * priv, int stream); 665 666 /** \brief Read audio samples 667 * \param priv The handle returned by the create() method 668 * \param frame The frame, where the samples will be copied 669 * \param stream Stream index starting with 0 670 * \param num_samples Number of samples 671 * \returns The number of decoded samples, 0 means EOF. 672 * 673 * The num_samples argument can be larger than the samples_per_frame member of the 674 * video format. This means, that all audio decoding plugins must have an internal 675 * buffering mechanism. 676 */ 677 678 bg_read_audio_func_t read_audio; 679 680 /** \brief Check is a still image is available 681 * \param priv The handle returned by the create() method 682 * \param stream Stream index starting with 0 683 * \returns 1 if a still frame can be decoded, 0 else. 684 * 685 * If EOF occurs in still streams, this function will return 686 * 1, but the subsequent call to read_video returns 0 687 */ 688 689 int (*has_still)(void * priv, int stream); 690 691 /** \brief Read a video frame 692 * \param priv The handle returned by the create() method 693 * \param frame The frame, where the image will be copied 694 * \param stream Stream index starting with 0 695 * \returns 1 if a frame was decoded, 0 means EOF. 696 */ 697 698 bg_read_video_func_t read_video; 699 700 /** \brief Read compressed audio packet 701 * \param priv The handle returned by the create() method 702 * \param stream Stream index (starting with 0) 703 * \param p Returns the packet 704 * \returns 1 if a packet was read, 0 else 705 * 706 * You can pass the same packet multiple times to a read fuction. 707 * Use \ref gavl_packet_free when it's no longer used. 708 */ 709 710 int (*read_audio_packet)(void * priv, int stream, gavl_packet_t * p); 711 712 /** \brief Read compressed video packet 713 * \param priv The handle returned by the create() method 714 * \param stream Stream index (starting with 0) 715 * \param p Returns the packet 716 * \returns 1 if a packet was read, 0 else 717 * 718 * You can pass the same packet multiple times to a read fuction. 719 * Use \ref gavl_packet_free when it's no longer used. 720 */ 721 722 int (*read_video_packet)(void * priv, int stream, gavl_packet_t * p); 723 724 725 /** \brief Skip frames in a video stream 726 \param stream Stream index (starting with 0) 727 \param time The time to skip to (will be changed to the true time) 728 \param scale Scale by which the time is scaled 729 \param exact 1 if an exact skip should be done, 0 for faster approximate skip 730 731 Use this function if it turns out, that the machine is too weak to 732 decode all frames. Set exact to 0 to make the skipping even faster 733 but less accurate. 734 735 */ 736 737 void (*skip_video)(void * priv, int stream, int64_t * time, int scale, int exact); 738 739 /** \brief Query if a new subtitle is available 740 * \param priv The handle returned by the create() method 741 * \param stream Stream index starting with 0 742 * \returns 1 if a subtitle is available, 0 else. 743 */ 744 745 int (*has_subtitle)(void * priv, int stream); 746 747 /** \brief Read one pixmap subtitle 748 * \param priv The handle returned by the create() method 749 * \param ovl Where the overlay will be copied 750 * \param stream Stream index starting with 0 751 * \returns 1 if a subtitle was decoded, 0 else 752 * 753 * EOF in a graphical subtitle stream is reached if 754 * - has_subtitle() returned 1 and 755 * - read_subtitle_overlay() returned 0 756 */ 757 758 int (*read_subtitle_overlay)(void * priv, 759 gavl_overlay_t*ovl, int stream); 760 761 /** \brief Read one text subtitle 762 * \param priv The handle returned by the create() method 763 * \param text Where the text will be copied, the buffer will be realloc()ed. 764 * \param text_alloc Allocated bytes for text. Will be updated by the function. 765 * \param start_time Returns the start time of the subtitle 766 * \param duration Returns the duration of the subtitle 767 * \param stream Stream index starting with 0 768 * \returns 1 if a subtitle was decoded, 0 else 769 * 770 * EOF in a text subtitle stream is reached if 771 * - has_subtitle() returned 1 and 772 * - read_subtitle_text() returned 0 773 * 774 * This function automatically handles the text buffer (and text_alloc). 775 * Just set both to zero before the first call and free() the text buffer 776 * after the last call (if non-NULL). 777 */ 778 779 int (*read_subtitle_text)(void * priv, 780 char ** text, int * text_alloc, 781 int64_t * start_time, 782 int64_t * duration, int stream); 783 784 /** \brief Seek within a media track 785 * \param priv The handle returned by the create() method 786 * \param time Time to seek to 787 * \param scale Timescale 788 * 789 * Media streams are supposed to be seekable, if this 790 * function is non-NULL AND the duration field of the track info 791 * is > 0 AND the seekable flag in the track info is nonzero. 792 * The time argument might be changed to the correct value 793 */ 794 795 void (*seek)(void * priv, int64_t * time, int scale); 796 797 /** \brief Stop playback 798 * \param priv The handle returned by the create() method 799 * 800 * This is used for plugins in bypass mode to stop playback. 801 * The plugin can be started again after 802 */ 803 804 void (*stop)(void * priv); 805 806 /** \brief Close plugin 807 * \param priv The handle returned by the create() method 808 * 809 * Close the file/device/url. 810 */ 811 812 void (*close)(void * priv); 813 814 }; 815 816 /** \defgroup plugin_oa Audio output 817 * \ingroup plugin 818 * \brief Audio output 819 */ 820 821 /** \ingroup plugin_oa 822 * \brief Typedef for audio output plugin 823 */ 824 825 typedef struct bg_oa_plugin_s bg_oa_plugin_t; 826 827 /** \ingroup plugin_oa 828 * \brief Audio output plugin 829 * 830 * This plugin type implements audio playback through a soundcard. 831 */ 832 833 struct bg_oa_plugin_s 834 { 835 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 836 837 /** \brief Open plugin 838 * \param priv The handle returned by the create() method 839 * \param format The format of the media source 840 * 841 * The format will be changed to the nearest format, which is supported 842 * by the plugin. To convert the source format to the output format, 843 * use a \ref gavl_audio_converter_t 844 */ 845 846 int (*open)(void * priv, gavl_audio_format_t* format); 847 848 /** \brief Start playback 849 * \param priv The handle returned by the create() method 850 * 851 * Notify the plugin, that audio playback is about to begin. 852 */ 853 854 int (*start)(void * priv); 855 856 /** \brief Write audio samples 857 * \param priv The handle returned by the create() method 858 * \param frame The audio frame to write. 859 */ 860 861 void (*write_audio)(void * priv, gavl_audio_frame_t* frame); 862 863 /** \brief Get the number of buffered audio samples 864 * \param priv The handle returned by the create() method 865 * \returns The number of buffered samples (both soft- and hardware) 866 * 867 * This function is used for A/V synchronization with the soundcard. If this 868 * function is NULL, software synchronization will be used 869 */ 870 871 int (*get_delay)(void * priv); 872 873 /** \brief Stop playback 874 * \param priv The handle returned by the create() method 875 * 876 * Notify the plugin, that playback will stop. Playback can be starzed again with 877 * start(). 878 */ 879 880 void (*stop)(void * priv); 881 882 /** \brief Close plugin 883 * \param priv The handle returned by the create() method 884 * 885 * Close the plugin. After this call, the plugin can be opened with another format 886 */ 887 888 void (*close)(void * priv); 889 }; 890 891 /******************************************* 892 * AUDIO RECORDER 893 *******************************************/ 894 895 /** \defgroup plugin_r Recorder 896 * \ingroup plugin 897 * \brief Recorder 898 */ 899 900 typedef struct bg_recorder_callbacks_s bg_recorder_callbacks_t; 901 902 /** \ingroup plugin_r 903 * \brief Callbacks for recorder plugins 904 * 905 * Passing the callback structure to the plugin is optional. Futhermore, 906 * any of the callback functions is optional (i.e. can be NULL). The plugin 907 * might use the callbacks for propagating events. 908 */ 909 910 struct bg_recorder_callbacks_s 911 { 912 /** \brief Name changed 913 * \param data The data member of this bg_input_callbacks_s struct 914 * \param name The new name 915 * \param metadata The new metadata 916 * 917 * This is for web-radio stations, which send song-names. 918 */ 919 920 void (*metadata_changed)(void * data, const char * name, 921 const gavl_metadata_t * m); 922 923 void * data; //!< Application specific data passed as the first argument to all callbacks. 924 925 }; 926 927 928 /** \ingroup plugin_r 929 * \brief Typedef for recorder 930 */ 931 932 typedef struct bg_recorder_plugin_s bg_recorder_plugin_t; 933 934 /** \ingroup plugin_ra 935 * \brief Recorder 936 * 937 * Recording support from hardware devices 938 */ 939 940 struct bg_recorder_plugin_s 941 { 942 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 943 944 /** \brief Set callbacks 945 * \param priv The handle returned by the create() method 946 * \param callbacks Callback structure initialized by the caller before 947 * 948 * Set callback functions, which will be called by the plugin. 949 * Defining as well as calling this function is optional. Any of the 950 * members of callbacks can be NULL. 951 */ 952 953 void (*set_callbacks)(void * priv, bg_recorder_callbacks_t * callbacks); 954 955 /** \brief Open plugin 956 * \param priv The handle returned by the create() method 957 * \param format The desired format 958 * 959 * The format will be changed to the nearest format, which is supported 960 * by the plugin. To convert the source format to the output format, 961 * use a \ref gavl_audio_converter_t 962 */ 963 964 965 int (*open)(void * priv, gavl_audio_format_t * audio_format, 966 gavl_video_format_t * video_format); 967 968 /** \brief Read audio samples 969 */ 970 bg_read_audio_func_t read_audio; 971 972 /** \brief Read video frame 973 */ 974 bg_read_video_func_t read_video; 975 976 /** \brief Close plugin 977 * \param priv The handle returned by the create() method 978 */ 979 980 void (*close)(void * priv); 981 }; 982 983 /******************************************* 984 * VIDEO OUTPUT 985 *******************************************/ 986 987 /* Callbacks */ 988 989 /** \defgroup plugin_ov Video output 990 * \ingroup plugin 991 * \brief Video output 992 */ 993 994 /** \ingroup plugin_ov 995 * \brief Typedef for callbacks for the video output plugin 996 * 997 */ 998 999 typedef struct bg_ov_callbacks_s bg_ov_callbacks_t; 1000 1001 /** \ingroup plugin_ov 1002 * \brief Callbacks for the video output plugin 1003 * 1004 */ 1005 1006 struct bg_ov_callbacks_s 1007 { 1008 /** \brief Accelerator map 1009 * 1010 * These contain accelerator keys, which get reported 1011 * through the accel_callback 1012 */ 1013 1014 const bg_accelerator_map_t * accel_map; 1015 1016 /** \brief Keyboard callback 1017 * \param data The data member of this bg_ov_callbacks_s struct 1018 * \param id The accelerator ID 1019 */ 1020 1021 int (*accel_callback)(void * data, int id); 1022 1023 /** \brief Keyboard callback 1024 * \param data The data member of this bg_ov_callbacks_s struct 1025 * \param key Key code (see \ref keycodes) 1026 * \param mask Modifier mask (see \ref keycodes) 1027 * \returns 1 if the event should further be processed, 0 else 1028 * 1029 * Although key_callback and accel_callback can be used at the same 1030 * time, accelerator_callback is preferred, because it allows registering 1031 * keyboard shortcuts in advance. This makes things more reliable, if 1032 * different modules (e.g. embedded visualization plugins) also want to 1033 * receive keybords events· 1034 */ 1035 1036 int (*key_callback)(void * data, int key, int mask); 1037 1038 /** \brief Keyboard release callback 1039 * \param data The data member of this bg_ov_callbacks_s struct 1040 * \param key Key code (see \ref keycodes) 1041 * \param mask Modifier mask (see \ref keycodes) 1042 * \returns 1 if the event should further be processed, 0 else 1043 */ 1044 1045 int (*key_release_callback)(void * data, int key, int mask); 1046 1047 /** \brief Mouse button callback 1048 * \param data The data member of this bg_ov_callbacks_s struct 1049 * \param x Horizontal cursor position in image coordinates 1050 * \param y Vertical cursor position in image coordinates 1051 * \param button Number of the mouse button, which was pressed (starting with 1) 1052 * \param mask State mask 1053 * \returns 1 if the event should further be processed, 0 else 1054 */ 1055 1056 int (*button_callback)(void * data, int x, int y, int button, int mask); 1057 1058 /** \brief Mouse button release callback 1059 * \param data The data member of this bg_ov_callbacks_s struct 1060 * \param x Horizontal cursor position in image coordinates 1061 * \param y Vertical cursor position in image coordinates 1062 * \param button Number of the mouse button, which was pressed (starting with 1) 1063 * \param mask State mask 1064 * \returns 1 if the event should further be processed, 0 else 1065 */ 1066 1067 int (*button_release_callback)(void * data, int x, int y, int button, int mask); 1068 1069 /** \brief Motion callback 1070 * \param data The data member of this bg_ov_callbacks_s struct 1071 * \param x Horizontal cursor position in image coordinates 1072 * \param y Vertical cursor position in image coordinates 1073 * \param mask State mask 1074 * \returns 1 if the event should further be processed, 0 else 1075 */ 1076 1077 int (*motion_callback)(void * data, int x, int y, int mask); 1078 1079 /** \brief Show/hide callback 1080 * \param data The data member of this bg_ov_callbacks_s struct 1081 * \param show 1 if the window is shown now, 0 if it is hidden. 1082 */ 1083 1084 void (*show_window)(void * data, int show); 1085 1086 /** \brief Brightness change callback 1087 * \param data The data member of this bg_ov_callbacks_s struct 1088 * \param val New value (0.0..1.0) 1089 * 1090 * This callback can be used to update OSD when the brightness changed. 1091 */ 1092 1093 void (*brightness_callback)(void * data, float val); 1094 1095 /** \brief Saturation change callback 1096 * \param data The data member of this bg_ov_callbacks_s struct 1097 * \param val New value (0.0..1.0) 1098 * 1099 * This callback can be used to update OSD when the saturation changed. 1100 */ 1101 1102 void (*saturation_callback)(void * data, float val); 1103 1104 /** \brief Contrast change callback 1105 * \param data The data member of this bg_ov_callbacks_s struct 1106 * \param val New value (0.0..1.0) 1107 * 1108 * This callback can be used to update OSD when the contrast changed. 1109 */ 1110 1111 void (*contrast_callback)(void * data, float val); 1112 1113 /** \brief Hue change callback 1114 * \param data The data member of this bg_ov_callbacks_s struct 1115 * \param val New value (0.0..1.0) 1116 * 1117 * This callback can be used to update OSD when the hue changed. 1118 */ 1119 1120 void (*hue_callback)(void * data, float val); 1121 1122 void * data;//!< Application specific data passed as the first argument to all callbacks. 1123 }; 1124 1125 /* Plugin structure */ 1126 1127 /** \ingroup plugin_ov 1128 * \brief Typedef for video output plugin 1129 */ 1130 1131 typedef struct bg_ov_plugin_s bg_ov_plugin_t; 1132 1133 /** \ingroup plugin_ov 1134 * \brief Video output plugin 1135 * 1136 * This handles video output and still-image display. 1137 * In a window based system, it will typically open a new window, 1138 * which is owned by the plugin. 1139 */ 1140 1141 struct bg_ov_plugin_s 1142 { 1143 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 1144 1145 /** \brief Set window 1146 * \param priv The handle returned by the create() method 1147 * \param window Window identifier 1148 * 1149 * Call this immediately after creation of the plugin to embed 1150 * video output into a foreign application. 1151 * For X11, the window identifier has the form 1152 * \<display_name\>:\<normal_id\>:\<fullscreen_id\>. 1153 */ 1154 1155 void (*set_window)(void * priv, const char * window_id); 1156 1157 /** \brief Get window 1158 * \param priv The handle returned by the create() method 1159 * \returns Window identifier 1160 */ 1161 1162 const char * (*get_window)(void * priv); 1163 1164 /** \brief Set window class 1165 * \param priv The handle returned by the create() method 1166 * \param name The name of the window 1167 * \param klass The class of the window 1168 * 1169 * This makes sense probably only in an X11 environment. 1170 * If the klass argument is the same for all windows of an 1171 * application, they, might be grouped together in the 1172 * window list. On X11 this results in a call to 1173 * XSetClassHint(). 1174 */ 1175 1176 void (*set_window_options)(void * priv, const char * name, 1177 const char * klass, 1178 const gavl_video_frame_t * icon, 1179 const gavl_video_format_t * icon_format); 1180 1181 /** \brief Set window title 1182 * \param priv The handle returned by the create() method 1183 * \param title The title for the window 1184 */ 1185 1186 void (*set_window_title)(void * priv, const char * title); 1187 1188 1189 /** \brief Set callbacks 1190 * \param priv The handle returned by the create() method 1191 * \param callbacks Callback structure initialized by the caller before 1192 */ 1193 1194 void (*set_callbacks)(void * priv, bg_ov_callbacks_t * callbacks); 1195 1196 /** \brief Open plugin 1197 * \param priv The handle returned by the create() method 1198 * \param format Video format 1199 * \param window_title Window title 1200 * 1201 * The format will be changed to the nearest format, which is supported 1202 * by the plugin. To convert the source format to the output format, 1203 * use a \ref gavl_video_converter_t 1204 */ 1205 1206 int (*open)(void * priv, gavl_video_format_t * format, int keep_aspect); 1207 1208 /** \brief Get a video frame for filling with data 1209 * \param priv The handle returned by the create() method 1210 */ 1211 1212 gavl_video_frame_t * (*get_frame)(void * priv); 1213 1214 /** \brief Add a stream for transparent overlays 1215 * \param priv The handle returned by the create() method 1216 * \param format Format of the overlays 1217 * \returns The index of the overlay stream 1218 * 1219 * It's up to the plugin, if they are realized in hardware or 1220 * with a gavl_overlay_blend_context_t, but they must be there. 1221 * add_overlay_stream() must be called after open() 1222 * 1223 * An application can have more than one overlay stream. Typical 1224 * is one for subtitles and one for OSD. 1225 */ 1226 1227 int (*add_overlay_stream)(void * priv, gavl_video_format_t * format); 1228 1229 /** \brief Allocate an overlay 1230 * \param priv The handle returned by the create() method 1231 * \param id The id returned by the add_overlay_stream() method 1232 * \returns a newly allocated overlay 1233 * 1234 * This optional method allocates an overlay in a plugin specific manner 1235 * (e.g. in a shared memory segment). If this funtion is defined, all overlays 1236 * which are passed to the plugin, must be allocated by this function. 1237 * Before the plugin is closed, all created overlays must be freed with 1238 * the destroy_overlay() method. 1239 */ 1240 1241 gavl_overlay_t * (*create_overlay)(void * priv, int id); 1242 1243 /** \brief Set an overlay for a specific stream 1244 * \param priv The handle returned by the create() method 1245 * \param stream Stream index returned by add_overlay_stream() 1246 * \param ovl New overlay or NULL 1247 */ 1248 1249 void (*set_overlay)(void * priv, int stream, gavl_overlay_t * ovl); 1250 1251 /** \brief Display a frame of a video stream 1252 * \param priv The handle returned by the create() method 1253 * \param frame Frame to display 1254 * 1255 * This is for video playback 1256 */ 1257 1258 void (*put_video)(void * priv, gavl_video_frame_t*frame); 1259 1260 /** \brief Display a still image 1261 * \param priv The handle returned by the create() method 1262 * \param frame Frame to display 1263 * 1264 * This function is like put_video() with the difference, that 1265 * the frame will be remembered and redisplayed, when an expose event 1266 * is received. 1267 */ 1268 1269 void (*put_still)(void * priv, gavl_video_frame_t*frame); 1270 1271 /** \brief Get all events from the queue and handle them 1272 * \param priv The handle returned by the create() method 1273 * 1274 * This function processes and handles all events, which were 1275 * received from the windowing system. It calls mouse and key-callbacks, 1276 * and redisplays the image when in still mode. 1277 */ 1278 1279 void (*handle_events)(void * priv); 1280 1281 /** \brief Update aspect ratio 1282 * \param priv The handle returned by the create() method 1283 * \param pixel_width New pixel width 1284 * \param pixel_height New pixel height 1285 */ 1286 1287 void (*update_aspect)(void * priv, int pixel_width, int pixel_height); 1288 1289 /** \brief Free a frame created with the create_frame() method. 1290 * \param priv The handle returned by the create() method 1291 * \param frame The frame to be freed 1292 */ 1293 // void (*destroy_frame)(void * priv, gavl_video_frame_t * frame); 1294 1295 /** \brief Free an overlay created with the create_overlay() method. 1296 * \param priv The handle returned by the create() method 1297 * \param id The id returned by the add_overlay_stream() method 1298 * \param ovl The overlay to be freed 1299 */ 1300 1301 void (*destroy_overlay)(void * priv, int id, gavl_overlay_t * ovl); 1302 1303 /** \brief Close the plugin 1304 * \param priv The handle returned by the create() method 1305 * 1306 * Close everything so the plugin can be opened with a differtent format 1307 * after. 1308 */ 1309 1310 void (*close)(void * priv); 1311 1312 /** \brief Show or hide the window 1313 * \param priv The handle returned by the create() method 1314 * \param show 1 for showing, 0 for hiding 1315 */ 1316 void (*show_window)(void * priv, int show); 1317 }; 1318 1319 /******************************************* 1320 * ENCODER 1321 *******************************************/ 1322 1323 /** \defgroup plugin_e Encoder 1324 * \ingroup plugin 1325 * \brief Encoder 1326 */ 1327 1328 /** \ingroup plugin_ov 1329 * \brief Typedef for callbacks for the encoder plugin 1330 * 1331 */ 1332 1333 typedef struct bg_encoder_callbacks_s bg_encoder_callbacks_t; 1334 1335 /** \ingroup plugin_ov 1336 * \brief Callbacks for the encoder plugin 1337 * 1338 */ 1339 1340 struct bg_encoder_callbacks_s 1341 { 1342 1343 /** \brief Output file callback 1344 * \param data The data member of this bg_ov_callbacks_s struct 1345 * \param filename Name of the created file 1346 * \returns 1 if the file may be created, 0 else 1347 * 1348 * This is called whenever an output file is created. 1349 */ 1350 1351 int (*create_output_file)(void * data, const char * filename); 1352 1353 /** \brief Temp file callback 1354 * \param data The data member of this bg_ov_callbacks_s struct 1355 * \param filename Name of the created file 1356 * \returns 1 if the file may be created, 0 else 1357 * 1358 * This is called whenever a temporary file is created. 1359 */ 1360 1361 int (*create_temp_file)(void * data, const char * filename); 1362 1363 void * data;//!< Application specific data passed as the first argument to all callbacks. 1364 }; 1365 1366 1367 /** \ingroup plugin_e 1368 * \brief Typedef for encoder plugin 1369 */ 1370 1371 typedef struct bg_encoder_plugin_s bg_encoder_plugin_t; 1372 1373 1374 /** \ingroup plugin_e 1375 * \brief Encoder plugin 1376 */ 1377 1378 struct bg_encoder_plugin_s 1379 { 1380 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 1381 1382 int max_audio_streams; //!< Maximum number of audio streams. -1 means infinite 1383 int max_video_streams; //!< Maximum number of video streams. -1 means infinite 1384 int max_subtitle_text_streams;//!< Maximum number of text subtitle streams. -1 means infinite 1385 int max_subtitle_overlay_streams;//!< Maximum number of overlay subtitle streams. -1 means infinite 1386 1387 /** \brief Set callbacks 1388 * \param priv The handle returned by the create() method 1389 * \param cb Callback structure 1390 */ 1391 1392 void (*set_callbacks)(void * priv, bg_encoder_callbacks_t * cb); 1393 1394 /** \brief Query for writing compressed audio packets 1395 * \param priv The handle returned by the create() method 1396 * \param format Format of the source 1397 * \param info Compression info 1398 * \returns 1 if stream compressed format can be written, 0 else 1399 * 1400 * Call this function after all global parameters are set. 1401 */ 1402 1403 int (*writes_compressed_audio)(void * priv, 1404 const gavl_audio_format_t * format, 1405 const gavl_compression_info_t * info); 1406 1407 /** \brief Query for writing compressed video packets 1408 * \param priv The handle returned by the create() method 1409 * \param format Format of the source 1410 * \param info Compression info 1411 * \returns 1 if stream compressed format can be written, 0 else 1412 * 1413 * Call this function after all global parameters are set. 1414 */ 1415 1416 int (*writes_compressed_video)(void * priv, 1417 const gavl_video_format_t * format, 1418 const gavl_compression_info_t * info); 1419 1420 /** \brief Open a file 1421 * \param priv The handle returned by the create() method 1422 * \param filename Name of the file to be opened (without extension!) 1423 * \param metadata Metadata to be written to the file 1424 * \param chapter_list Chapter list (optional, can be NULL) 1425 * 1426 * The extension is added automatically by the plugin. 1427 * To keep track of the written files, use the \ref bg_encoder_callbacks_t. 1428 */ 1429 1430 int (*open)(void * data, const char * filename, 1431 const gavl_metadata_t * metadata, 1432 const bg_chapter_list_t * chapter_list); 1433 1434 /* Return per stream parameters */ 1435 1436 /** \brief Get audio related parameters 1437 * \param priv The handle returned by the create() method 1438 * \returns NULL terminated array of parameter descriptions 1439 * 1440 * The returned parameters are owned by the plugin and must not be freed. 1441 */ 1442 1443 const bg_parameter_info_t * (*get_audio_parameters)(void * priv); 1444 1445 /** \brief Get video related parameters 1446 * \param priv The handle returned by the create() method 1447 * \returns NULL terminated array of parameter descriptions 1448 * 1449 * The returned parameters are owned by the plugin and must not be freed. 1450 */ 1451 1452 const bg_parameter_info_t * (*get_video_parameters)(void * priv); 1453 1454 /** \brief Get text subtitle related parameters 1455 * \param priv The handle returned by the create() method 1456 * \returns NULL terminated array of parameter descriptions 1457 * 1458 * The returned parameters are owned by the plugin and must not be freed. 1459 */ 1460 1461 const bg_parameter_info_t * (*get_subtitle_text_parameters)(void * priv); 1462 1463 /** \brief Get overlay subtitle related parameters 1464 * \param priv The handle returned by the create() method 1465 * \returns NULL terminated array of parameter descriptions 1466 * 1467 * The returned parameters are owned by the plugin and must not be freed. 1468 */ 1469 1470 const bg_parameter_info_t * (*get_subtitle_overlay_parameters)(void * priv); 1471 1472 /* Add streams. The formats can be changed, be sure to get the 1473 * final formats with get_[audio|video]_format after starting the plugin 1474 * Return value is the index of the added stream. 1475 */ 1476 1477 /** \brief Add an audio stream 1478 * \param priv The handle returned by the create() method 1479 * \param language as ISO 639-2 code (3 characters+'\\0') or NULL 1480 * \param format Format of the source 1481 * \returns Index of this stream (starting with 0) 1482 * 1483 * The format might be changed to the nearest format supported by 1484 * the plugin. Use \ref get_audio_format to get the actual format 1485 * needed by the plugin, after \ref start() was called. 1486 */ 1487 1488 int (*add_audio_stream)(void * priv, const gavl_metadata_t * m, 1489 const gavl_audio_format_t * format); 1490 1491 /** \brief Add an audio stream fpr compressed writing 1492 * \param priv The handle returned by the create() method 1493 * \param language as ISO 639-2 code (3 characters+'\\0') or NULL 1494 * \param format Format of the source 1495 * \param info Compression info of the source 1496 * \returns Index of this stream (starting with 0) 1497 * 1498 * The format might be changed to the nearest format supported by 1499 * the plugin. Use \ref get_audio_format to get the actual format 1500 * needed by the plugin, after \ref start() was called. 1501 */ 1502 1503 int (*add_audio_stream_compressed)(void * priv, const gavl_metadata_t * m, 1504 const gavl_audio_format_t * format, 1505 const gavl_compression_info_t * info); 1506 1507 /** \brief Add a video stream 1508 * \param priv The handle returned by the create() method 1509 * \param format Format of the source 1510 * \returns Index of this stream (starting with 0) 1511 * 1512 * The format might be changed to the nearest format supported by 1513 * the plugin. Use \ref get_video_format to get the actual format 1514 * needed by the plugin, after \ref start() was called. 1515 */ 1516 1517 int (*add_video_stream)(void * priv, 1518 const gavl_metadata_t * m, 1519 const gavl_video_format_t * format); 1520 1521 /** \brief Add a video stream for compressed writing 1522 * \param priv The handle returned by the create() method 1523 * \param format Format of the source 1524 * \param info Compression info of the source 1525 * \returns Index of this stream (starting with 0) 1526 * 1527 * The format might be changed to the nearest format supported by 1528 * the plugin. Use \ref get_video_format to get the actual format 1529 * needed by the plugin, after \ref start() was called. 1530 */ 1531 1532 int (*add_video_stream_compressed)(void * priv, 1533 const gavl_metadata_t * m, 1534 const gavl_video_format_t * format, 1535 const gavl_compression_info_t * info); 1536 1537 /** \brief Add a text subtitle stream 1538 * \param priv The handle returned by the create() method 1539 * \param language as ISO 639-2 code (3 characters+'\\0') or NULL 1540 * \returns Index of this stream (starting with 0) 1541 */ 1542 1543 int (*add_subtitle_text_stream)(void * priv, 1544 const gavl_metadata_t * m, 1545 int * timescale); 1546 1547 /** \brief Add a text subtitle stream 1548 * \param priv The handle returned by the create() method 1549 * \param language as ISO 639-2 code (3 characters+'\\0') or NULL 1550 * \param format Format of the source 1551 * \returns Index of this stream (starting with 0) 1552 * 1553 * The format might be changed to the nearest format supported by 1554 * the plugin. Use \ref get_subtitle_overlay_format 1555 * to get the actual format 1556 * needed by the plugin, after \ref start was called. 1557 */ 1558 1559 int (*add_subtitle_overlay_stream)(void * priv, 1560 const gavl_metadata_t * m, 1561 const gavl_video_format_t * format); 1562 1563 /* Set parameters for the streams */ 1564 1565 /** \brief Set audio encoding parameter 1566 * \param priv The handle returned by the create() method 1567 * \param stream Stream index (starting with 0) 1568 * \param name Name of the parameter 1569 * \param v Value 1570 * 1571 * Use this function with parameters obtained by 1572 * \ref get_audio_parameters. 1573 */ 1574 1575 void (*set_audio_parameter)(void * priv, int stream, const char * name, 1576 const bg_parameter_value_t * v); 1577 1578 /** \brief Set video encoding parameter 1579 * \param priv The handle returned by the create() method 1580 * \param stream Stream index (starting with 0) 1581 * \param name Name of the parameter 1582 * \param v Value 1583 * 1584 * Use this function with parameters obtained by 1585 * \ref get_video_parameters. 1586 */ 1587 1588 1589 void (*set_video_parameter)(void * priv, int stream, const char * name, 1590 const bg_parameter_value_t * v); 1591 1592 /** \brief Set text subtitle encoding parameter 1593 * \param priv The handle returned by the create() method 1594 * \param stream Stream index (starting with 0) 1595 * \param name Name of the parameter 1596 * \param v Value 1597 * 1598 * Use this function with parameters obtained by 1599 * \ref get_subtitle_text_parameters. 1600 */ 1601 1602 void (*set_subtitle_text_parameter)(void * priv, int stream, 1603 const char * name, 1604 const bg_parameter_value_t * v); 1605 1606 /** \brief Set text subtitle encoding parameter 1607 * \param priv The handle returned by the create() method 1608 * \param stream Stream index (starting with 0) 1609 * \param name Name of the parameter 1610 * \param v Value 1611 * 1612 * Use this function with parameters obtained by 1613 * \ref get_subtitle_overlay_parameters. 1614 */ 1615 1616 void (*set_subtitle_overlay_parameter)(void * priv, int stream, 1617 const char * name, 1618 const bg_parameter_value_t * v); 1619 1620 /** \brief Setup multipass video encoding. 1621 * \param priv The handle returned by the create() method 1622 * \param stream Stream index (starting with 0) 1623 * \param pass Number of this pass (starting with 1) 1624 * \param total_passes Number of total passes 1625 * \param stats_file Name of a file, which can be used for multipass statistics 1626 * \returns 0 if multipass transcoding is not supported and can be ommitted, 1 else 1627 */ 1628 int (*set_video_pass)(void * priv, int stream, int pass, int total_passes, 1629 const char * stats_file); 1630 1631 /** \brief Set up all codecs and prepare for encoding 1632 * \param priv The handle returned by the create() method 1633 * \returns 0 on error, 1 on success 1634 * 1635 * Optional function for preparing the actual encoding. Applications must 1636 * check for this function and call it when available. 1637 */ 1638 1639 int (*start)(void * priv); 1640 1641 /* 1642 * After setting the parameters, get the formats, you need to deliver the frames in 1643 */ 1644 1645 /** \brief Get audio format 1646 * \param priv The handle returned by the create() method 1647 * \param stream Stream index (starting with 0) 1648 * \param ret Returns format 1649 * 1650 * Call this after calling \ref start() if it's defined. 1651 */ 1652 1653 void (*get_audio_format)(void * priv, int stream, gavl_audio_format_t*ret); 1654 1655 /** \brief Get video format 1656 * \param priv The handle returned by the create() method 1657 * \param stream Stream index (starting with 0) 1658 * \param ret Returns format 1659 * 1660 * Call this after calling \ref start() if it's defined. 1661 */ 1662 1663 void (*get_video_format)(void * priv, int stream, gavl_video_format_t*ret); 1664 1665 /** \brief Get video format of an overlay subtitle stream 1666 * \param priv The handle returned by the create() method 1667 * \param stream Stream index (starting with 0) 1668 * \param ret Returns format 1669 * 1670 * Call this after calling \ref start() if it's defined. 1671 */ 1672 1673 void (*get_subtitle_overlay_format)(void * priv, int stream, 1674 gavl_video_format_t*ret); 1675 1676 /* 1677 * Encode audio/video 1678 */ 1679 1680 /** \brief Write audio samples 1681 * \param priv The handle returned by the create() method 1682 * \param frame Frame with samples 1683 * \param stream Stream index (starting with 0) 1684 * \returns 1 is the data was successfully written, 0 else 1685 * 1686 * The actual number of samples must be stored in the valid_samples member of 1687 * the frame. 1688 */ 1689 1690 int (*write_audio_frame)(void * data, gavl_audio_frame_t * frame, int stream); 1691 1692 /** \brief Write audio packet 1693 * \param priv The handle returned by the create() method 1694 * \param packet Packet with compressed data 1695 * \param stream Stream index (starting with 0) 1696 * \returns 1 is the data was successfully written, 0 else 1697 * 1698 * The actual number of samples must be stored in the duration member of 1699 * the packet. 1700 */ 1701 1702 int (*write_audio_packet)(void * data, gavl_packet_t * packet, int stream); 1703 1704 1705 /** \brief Write video frame 1706 * \param priv The handle returned by the create() method 1707 * \param frame Frame 1708 * \param stream Stream index (starting with 0) 1709 * \returns 1 is the data was successfully written, 0 else 1710 */ 1711 1712 int (*write_video_frame)(void * data, gavl_video_frame_t * frame, int stream); 1713 1714 /** \brief Write video packet 1715 * \param priv The handle returned by the create() method 1716 * \param packet Packet with compressed data 1717 * \param stream Stream index (starting with 0) 1718 * \returns 1 is the data was successfully written, 0 else 1719 */ 1720 1721 int (*write_video_packet)(void * data, gavl_packet_t * packet, int stream); 1722 1723 /** \brief Write a text subtitle 1724 * \param priv The handle returned by the create() method 1725 * \param frame The text 1726 * \param start Start of the subtitle 1727 * \param duration Duration of the subtitle 1728 * \param stream Stream index (starting with 0) 1729 * \returns 1 is the data was successfully written, 0 else 1730 */ 1731 1732 int (*write_subtitle_text)(void * data,const char * text, 1733 int64_t start, 1734 int64_t duration, int stream); 1735 1736 /** \brief Write an overlay subtitle 1737 * \param priv The handle returned by the create() method 1738 * \param ovl An overlay 1739 * \param stream Stream index (starting with 0) 1740 * \returns 1 is the data was successfully written, 0 else 1741 */ 1742 1743 int (*write_subtitle_overlay)(void * data, gavl_overlay_t * ovl, int stream); 1744 1745 /** \brief Update metadata 1746 * \param data The data member of this bg_input_callbacks_s struct 1747 * \param name Name 1748 * \param m Metadata 1749 * 1750 * Update metadata for broadcasting plugins. 1751 * Either name or m can be NULL. 1752 */ 1753 1754 void (*update_metadata)(void * data, const char * name, 1755 const gavl_metadata_t * m); 1756 1757 /** \brief Close encoder 1758 * \param priv The handle returned by the create() method 1759 * \param do_delete Set this to 1 to delete all created files 1760 * \returns 1 is the file was sucessfully closed, 0 else 1761 * 1762 * After calling this function, the plugin should be destroyed. 1763 */ 1764 1765 int (*close)(void * data, int do_delete); 1766 }; 1767 1768 1769 /******************************************* 1770 * ENCODER Postprocessor 1771 *******************************************/ 1772 1773 /** \defgroup plugin_e_pp Encoding postprocessor 1774 * \ingroup plugin 1775 * \brief Encoding postprocessor 1776 * 1777 * The postprocessing plugins take one or more files 1778 * for further processing them. There are postprocessors 1779 * for creating and (optionally) burning audio CDs and VCDs. 1780 */ 1781 1782 /** \ingroup plugin_e_pp 1783 * \brief Callbacks for postprocessing 1784 * 1785 */ 1786 1787 typedef struct 1788 { 1789 /** \brief Callback describing the current action 1790 * \param data The data member of this bg_ov_callbacks_s struct 1791 * \param action A string describing the current action 1792 * 1793 * Action can be something like "Burning track 1/10". 1794 */ 1795 void (*action_callback)(void * data, char * action); 1796 1797 /** \brief Callback describing the progress of the current action 1798 * \param data The data member of this bg_ov_callbacks_s struct 1799 * \param perc Percentage (0.0 .. 1.0) 1800 * 1801 * This is exclusively for updating progress bars in 1802 * GUI applications. Note, that some postprocessors 1803 * reset the progress during postprocessing. 1804 */ 1805 1806 void (*progress_callback)(void * data, float perc); 1807 1808 void * data; //!< Application specific data passed as the first argument to all callbacks. 1809 1810 } bg_e_pp_callbacks_t; 1811 1812 /** \ingroup plugin_e_pp 1813 * \brief Typedef for encoding postprocessor 1814 * 1815 */ 1816 1817 typedef struct bg_encoder_pp_plugin_s bg_encoder_pp_plugin_t; 1818 1819 /** \ingroup plugin_e_pp 1820 * \brief Encoding postprocessor 1821 * 1822 */ 1823 1824 struct bg_encoder_pp_plugin_s 1825 { 1826 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 1827 1828 int max_audio_streams; //!< Maximum number of audio streams. -1 means infinite 1829 int max_video_streams; //!< Maximum number of video streams. -1 means infinite 1830 1831 char * supported_extensions; //!< Supported file extensions (space separated) 1832 1833 /** \brief Set callbacks 1834 * \param priv The handle returned by the create() method 1835 * \param callbacks Callback structure initialized by the caller before 1836 * 1837 */ 1838 1839 void (*set_callbacks)(void * priv,bg_e_pp_callbacks_t * callbacks); 1840 1841 /** \brief Initialize 1842 * \param priv The handle returned by the create() method 1843 * 1844 * This functions clears all tracks and makes the plugin ready to 1845 * add new tracks. 1846 */ 1847 1848 int (*init)(void * priv); 1849 1850 /** \brief Add a transcoded track 1851 * \param priv The handle returned by the create() method 1852 * \param filename Name of the media file 1853 * \param metadata Metadata for the track 1854 * \param pp_only Set this to 1 if this file was not encoded and is only postprocessed 1855 * 1856 * Send a track to the postprocessor. This plugin will store all necessary data until 1857 * the \ref run() method is called. Some postprocessors might do some sanity tests 1858 * on the file e.g. the audio CD burner will reject anything except WAV-files. 1859 * 1860 * Usually, it is assumed, that files were encoded for the only purpose of postprocessing 1861 * them. This means, they will be deleted if the cleanup flag is passed to the \ref run() 1862 * function. If you set the pp_only argument to 1, you tell, that this file should be 1863 * kept after postprocessing. 1864 */ 1865 1866 void (*add_track)(void * priv, const char * filename, 1867 gavl_metadata_t * metadata, int pp_only); 1868 1869 /** \brief Start postprocessing 1870 * \param priv The handle returned by the create() method 1871 * \param directory The directory, where output files can be written 1872 * \param cleanup Set this to 1 to erase all source files and temporary files after finishing 1873 * Run can be a long operation, it should be called from a separate 1874 * thread launched by the application and the callbacks should be 1875 * used for progress reporting 1876 */ 1877 1878 void (*run)(void * priv, const char * directory, int cleanup); 1879 1880 /** \brief Stop postprocessing 1881 * \param priv The handle returned by the create() method 1882 * 1883 * Call this function to cancel a previously called \ref run() function. 1884 * The plugin must implement the stop mechanism in a thread save manner, 1885 * i.e. the stop method must savely be callable from another thread than the 1886 * one, which called \ref run(). 1887 */ 1888 1889 void (*stop)(void * priv); 1890 }; 1891 1892 1893 /** \defgroup plugin_ir Image support 1894 * \ingroup plugin 1895 * \brief Read and write image files 1896 * 1897 * These support reading and writing of images in a variety 1898 * of formats 1899 * 1900 * @{ 1901 */ 1902 1903 /** \brief Typedef for image reader plugin 1904 */ 1905 1906 typedef struct bg_image_reader_plugin_s bg_image_reader_plugin_t; 1907 1908 /** \brief Image reader plugin 1909 */ 1910 1911 struct bg_image_reader_plugin_s 1912 { 1913 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 1914 const char * extensions; //!< Supported file extensions (space separated) 1915 1916 /** \brief Read the file header 1917 * \param priv The handle returned by the create() method 1918 * \param filename Filename 1919 * \param format Returns the format of the image 1920 * \returns 1 on success, 0 on error. 1921 */ 1922 1923 int (*read_header)(void * priv, const char * filename, 1924 gavl_video_format_t * format); 1925 1926 /** \brief Get metadata 1927 * \param priv The handle returned by the create() method 1928 * \returns Metadata for the image or NULL 1929 */ 1930 1931 const gavl_metadata_t * (*get_metadata)(void * priv); 1932 1933 /** \brief Get compression info 1934 * \param priv The handle returned by the create() method 1935 * \param ci Returns the compression info 1936 * \returns 1 if the compression info could be returned, 0 else 1937 */ 1938 1939 int (*get_compression_info)(void * priv, gavl_compression_info_t * ci); 1940 1941 /** \brief Read the image 1942 * \param priv The handle returned by the create() method 1943 * \param frame The frame, where the image will be copied 1944 * \returns 1 if the image was read, 0 else 1945 * 1946 * After reading the image the plugin is cleaned up, so \ref read_header() 1947 * can be called again after that. If frame is NULL, no image is read, 1948 * and the plugin is reset. 1949 */ 1950 int (*read_image)(void * priv, gavl_video_frame_t * frame); 1951 }; 1952 1953 /** 1954 * \brief Typedef for callbacks for the image writer plugin 1955 */ 1956 1957 typedef struct bg_iw_callbacks_s bg_iw_callbacks_t; 1958 1959 /** 1960 * \brief Callbacks for the image writer plugin 1961 */ 1962 1963 struct bg_iw_callbacks_s 1964 { 1965 1966 /** \brief Output file callback 1967 * \param data The data member of this bg_ov_callbacks_s struct 1968 * \param filename Name of the created file 1969 * \returns 1 if the file may be created, 0 else 1970 * 1971 * This is called whenever an output file is created. 1972 */ 1973 1974 int (*create_output_file)(void * data, const char * filename); 1975 1976 void * data;//!< Application specific data passed as the first argument to all callbacks. 1977 }; 1978 1979 /** \brief Typedef for image writer plugin 1980 * 1981 */ 1982 1983 typedef struct bg_image_writer_plugin_s bg_image_writer_plugin_t; 1984 1985 /** \brief Image writer plugin 1986 * 1987 */ 1988 1989 struct bg_image_writer_plugin_s 1990 { 1991 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 1992 const char * extensions; //!< File extensions (space separated) 1993 1994 /** \brief Set callbacks 1995 * \param priv The handle returned by the create() method 1996 * \param cb Callback structure 1997 */ 1998 1999 void (*set_callbacks)(void * priv, bg_iw_callbacks_t * cb); 2000 2001 /** \brief Write the file header 2002 * \param priv The handle returned by the create() method 2003 * \param format Video format 2004 * \returns 1 on success, 0 on error. 2005 * 2006 * The format will be changed to the nearest format, which is supported 2007 * by the plugin. To convert the source format to the output format, 2008 * use a \ref gavl_video_converter_t 2009 */ 2010 2011 int (*write_header)(void * priv, const char * filename, 2012 gavl_video_format_t * format, const gavl_metadata_t * m); 2013 2014 /** \brief Write the image 2015 * \param priv The handle returned by the create() method 2016 * \param frame The frame containing the image 2017 * \returns 1 on success, 0 on error. 2018 * 2019 * After writing the image the plugin is cleaned up, so \ref write_header() 2020 * can be called again after that. If frame is NULL, no image is read, 2021 * and the plugin is reset. 2022 */ 2023 2024 int (*write_image)(void * priv, gavl_video_frame_t * frame); 2025 } ; 2026 2027 /** 2028 * @} 2029 */ 2030 2031 2032 /** \defgroup plugin_filter A/V Filters 2033 * \ingroup plugin 2034 * \brief A/V Filters 2035 2036 * These can apply additional effects to uncomporessed A/V data. 2037 * The API follows an asynchronous pull approach: You pass a callback 2038 * for reading input frames. Then you call the read method to read one 2039 * output frame. The plugin will read input data via the callback. 2040 * 2041 * This mechanism allows filters, where the numbers of input frames/samples 2042 * differs from the numbers of output frames/samples (e.g. when the filter 2043 * does framerate conversion). 2044 * 2045 * In principle, the API also supports filters with multiple input ports, 2046 * but currently, only plugins with one input are available. 2047 * 2048 * Not all filters support all formats. Applications should build filter chains 2049 * with format converters between them. There are, however, some standard formats, 2050 * which are supported by almost all filters, so the overall conversion overhead 2051 * is usually zero in real-life situations. 2052 * 2053 * @{ 2054 */ 2055 2056 2057 /* Filters */ 2058 2059 /** \brief Typedef for audio filter plugin 2060 * 2061 */ 2062 2063 typedef struct bg_fa_plugin_s bg_fa_plugin_t; 2064 2065 /** \brief Audio filter plugin 2066 * 2067 */ 2068 2069 struct bg_fa_plugin_s 2070 { 2071 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 2072 2073 /** \brief Set input callback 2074 * \param priv The handle returned by the create() method 2075 * \param func The function to call 2076 * \param data The private handle to pass to func 2077 * \param stream The stream argument to pass to func 2078 * \param port The input port of the plugin 2079 */ 2080 2081 void (*connect_input_port)(void * priv, bg_read_audio_func_t func, 2082 void * data, 2083 int stream, int port); 2084 2085 /** \brief Set input format 2086 * \param priv The handle returned by the create() method 2087 * \param format Format 2088 * \param port The input port of the plugin 2089 * 2090 * The input format can be changed by the plugin. Make sure that you have a format 2091 * converter before the filter. 2092 */ 2093 2094 void (*set_input_format)(void * priv, gavl_audio_format_t * format, int port); 2095 2096 2097 /** \brief Reset 2098 * \param priv The handle returned by the create() method 2099 * 2100 * Optional, resets internal state, as if no frame has been processed before. 2101 */ 2102 2103 void (*reset)(void * priv); 2104 2105 /** \brief Get output format 2106 * \param priv The handle returned by the create() method 2107 * \param format Returns the output format 2108 * 2109 * These must be called after init(). 2110 */ 2111 2112 void (*get_output_format)(void * priv, gavl_audio_format_t * format); 2113 2114 /** \brief Report, if the plugin must be reinitialized 2115 * \param priv The handle returned by the create() method 2116 * \returns 1 if the plugin must be reinitialized, 0 else 2117 * 2118 * Optional, must be called after set_parameter() to check, if the 2119 * filter must be reinitialized. Note, that the input and output formats can 2120 * be changed in this case as well. 2121 */ 2122 2123 int (*need_restart)(void * priv); 2124 2125 /** \brief Read audio samples from the plugin 2126 */ 2127 2128 bg_read_audio_func_t read_audio; 2129 2130 }; 2131 2132 /** \brief Typedef for video filter plugin 2133 * 2134 */ 2135 2136 typedef struct bg_fv_plugin_s bg_fv_plugin_t; 2137 2138 /** \brief Video filter plugin 2139 * 2140 */ 2141 2142 struct bg_fv_plugin_s 2143 { 2144 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 2145 2146 /** \brief Get gavl options 2147 * \param priv The handle returned by the create() method 2148 * \returns Video conversion options 2149 * 2150 * This optional function returns the gavl options. You can configure them 2151 * like you do it in plain gavl. 2152 */ 2153 2154 gavl_video_options_t * (*get_options)(void * priv); 2155 2156 /** \brief Set input callback 2157 * \param priv The handle returned by the create() method 2158 * \param func The function to call 2159 * \param data The private handle to pass to func 2160 * \param stream The stream argument to pass to func 2161 * \param port The input port of the plugin 2162 */ 2163 2164 void (*connect_input_port)(void * priv, 2165 bg_read_video_func_t func, 2166 void * data, int stream, int port); 2167 2168 /** \brief Set input format 2169 * \param priv The handle returned by the create() method 2170 * \param format Format 2171 * \param port The input port of the plugin 2172 */ 2173 2174 void (*set_input_format)(void * priv, gavl_video_format_t * format, int port); 2175 2176 /** \brief Reset 2177 * \param priv The handle returned by the create() method 2178 * 2179 * Optional, resets internal state, as if no frame has been processed before. 2180 */ 2181 2182 void (*reset)(void * priv); 2183 2184 /** \brief Get output format 2185 * \param priv The handle returned by the create() method 2186 * \param format Returns the output format 2187 * 2188 * These must be called after init(). 2189 */ 2190 2191 void (*get_output_format)(void * priv, gavl_video_format_t * format); 2192 2193 /** \brief Report, if the plugin must be reinitialized 2194 * \param priv The handle returned by the create() method 2195 * \returns 1 if the plugin must be reinitialized, 0 else 2196 * 2197 * Optional, must be called after set_parameter() to check, if the 2198 * filter must be reinitialized. Note, that the input and output formats can 2199 * be changed in this case as well. 2200 */ 2201 2202 int (*need_restart)(void * priv); 2203 2204 /** \brief Read a video frame from the plugin 2205 */ 2206 2207 bg_read_video_func_t read_video; 2208 2209 }; 2210 2211 2212 /** 2213 * @} 2214 */ 2215 2216 2217 /** \defgroup plugin_visualization Audio Visualization plugins 2218 * \ingroup plugin 2219 * \brief Audio Visualization plugins 2220 * 2221 * 2222 * 2223 * @{ 2224 */ 2225 2226 /** \brief Typedef for audio visualization plugin 2227 * 2228 */ 2229 2230 typedef struct bg_visualization_plugin_s bg_visualization_plugin_t; 2231 2232 2233 /** \brief Audio visualization plugin 2234 * 2235 * These plugins get audio samples and run visualizations of them. 2236 * Output can be either into a \ref gavl_video_frame_t or directly 2237 * via OpenGL. Which method is used is denoted by the 2238 * \ref BG_PLUGIN_VISUALIZE_FRAME and \ref BG_PLUGIN_VISUALIZE_GL 2239 * flags. 2240 * 2241 * For OpenGL, you need to pass a window ID to the 2242 * plugin. The plugin is then responsible for creating Subwindows and 2243 * setting up an OpenGL context. In General, it's stronly recommended to 2244 * use the \ref bg_visualizer_t module to use visualizations. 2245 */ 2246 2247 struct bg_visualization_plugin_s 2248 { 2249 bg_plugin_common_t common; //!< Infos and functions common to all plugin types 2250 2251 /** \brief return callback 2252 * \param priv The handle returned by the create() method 2253 * \param cb The callbacks to be called 2254 */ 2255 2256 void (*set_callbacks)(void * priv, bg_ov_callbacks_t * cb); 2257 2258 /** \brief Open a frame based visualization plugin 2259 * \param priv The handle returned by the create() method 2260 * \param audio_format Audio format 2261 * \param video_format Video format 2262 * 2263 * The audio format parameter will most likely changed to the 2264 * nearest supported format. In the video format parameter, you 2265 * usually pass the desired render size. Everything else 2266 * (except the framerate) will be set up by the plugin. 2267 */ 2268 2269 int (*open_ov)(void * priv, gavl_audio_format_t * audio_format, 2270 gavl_video_format_t * video_format); 2271 2272 /** \brief Open a window based visualization plugin 2273 * \param priv The handle returned by the create() method 2274 * \param audio_format Audio format 2275 * \param window_id A window ID 2276 * 2277 * The audio format parameter will most likely changed to the 2278 * nearest supported format. For the window id, use strings formatted 2279 * like the one returned by \ref bg_ov_plugin_t 2280 2281 */ 2282 int (*open_win)(void * priv, gavl_audio_format_t * audio_format, 2283 const char * window_id); 2284 2285 /** \brief Send audio data to the plugin 2286 * \param priv The handle returned by the create() method 2287 * \param frame Audio frame 2288 * 2289 * This updates the plugin with new audio samples. After that, we may 2290 * or may not call the draw_frame function below to actually draw an 2291 * image. Note, that visualization plugins are not required to do 2292 * internal audio buffering, so it's wise to pass a frame with as many 2293 * samples as the samples_per_frame member of the audio format returned 2294 * by \ref open_ov or \ref open_win. 2295 */ 2296 2297 void (*update)(void * priv, gavl_audio_frame_t * frame); 2298 2299 /** \brief Draw an image 2300 * \param priv The handle returned by the create() method 2301 * \param The video frame to draw to 2302 * 2303 * For OpenGL plugins, frame is NULL. For frame based plugins, 2304 * the image will be drawn into the frame you pass. You must display 2305 * the frame on your own then. 2306 */ 2307 2308 void (*draw_frame)(void * priv, gavl_video_frame_t * frame); 2309 2310 /** \brief Show the image 2311 * \param priv The handle returned by the create() method 2312 * 2313 * This function is needed only for OpenGL plugins. Under X11, 2314 * it will typically call glXSwapBuffers and process events on the 2315 * X11 window. 2316 */ 2317 2318 void (*show_frame)(void * priv); 2319 2320 /** \brief Close a plugin 2321 * \param priv The handle returned by the create() method 2322 */ 2323 2324 void (*close)(void * priv); 2325 2326 }; 2327 2328 2329 2330 /** 2331 * @} 2332 */ 2333 2334 #endif // __BG_PLUGIN_H_ 2335