1 // liblives.hpp 2 // LiVES (lives-exe) 3 // (c) G. Finch <salsaman+lives@gmail.com> 2015 - 2018 4 // Released under the GPL 3 or later 5 // see file ../COPYING for licensing details 6 7 /** \file liblives.hpp 8 Header file for liblives. 9 */ 10 11 #ifndef HAS_LIBLIVES_H 12 #define HAS_LIBLIVES_H 13 14 /** 15 Version number major 16 */ 17 #define LIVES_VERSION_MAJOR 3 18 19 /** 20 Version number minor 21 */ 22 #define LIVES_VERSION_MINOR 2 23 24 /** 25 Version number micro 26 */ 27 #define LIVES_VERSION_MICRO 0 28 29 /** 30 Macro to check if livesApp version is >= major.minor.micro 31 */ 32 #define LIVES_CHECK_VERSION(major, minor, micro) (major > LIVES_VERSION_MAJOR || (major == LIVES_VERSION_MAJOR && (minor > LIVES_VERSION_MINOR || (minor == LIVES_VERSION_MINOR && micro >= LIVES_VERSION_MICRO)))) ///< 33 34 // defs shared with lbindings.c 35 36 /** 37 Filechooser hinting types 38 */ 39 typedef enum { 40 LIVES_FILE_CHOOSER_VIDEO_AUDIO, ///< file chooser options for single video or audio file 41 LIVES_FILE_CHOOSER_AUDIO_ONLY, ///< file chooser options for single audio file 42 // LIVES_FILE_CHOOSER_VIDEO_AUDIO_MULTI, ///< file chooser options for multiple video or audio files 43 //LIVES_FILE_CHOOSER_VIDEO_RANGE ///< file chooser options for video range (start time/number of frames) 44 } lives_filechooser_t; 45 46 /** 47 LiVES operation mode 48 */ 49 typedef enum { 50 LIVES_INTERFACE_MODE_INVALID = -1, ///< livesApp instance is invalid 51 LIVES_INTERFACE_MODE_CLIPEDIT, ///< clip editor mode 52 LIVES_INTERFACE_MODE_MULTITRACK ///< multitrack mode 53 } lives_interface_mode_t; 54 55 56 /** 57 LiVES operational status 58 */ 59 typedef enum { 60 LIVES_STATUS_INVALID = -1, ///< livesApp instance is invalid 61 LIVES_STATUS_NOTREADY, ///< application is starting up; not ready 62 LIVES_STATUS_READY, ///< application is ready for commands 63 LIVES_STATUS_PLAYING, ///< application is playing, only player commands will be responded to 64 LIVES_STATUS_PROCESSING, ///< application is processing, commands will be ignored 65 LIVES_STATUS_PREVIEW ///< user is previewing an operation, commands will be ignored 66 } lives_status_t; 67 68 69 /** 70 Endian values 71 */ 72 typedef enum { 73 LIVES_LITTLEENDIAN, 74 LIVES_BIGENDIAN 75 } lives_endian_t; 76 77 78 /** 79 Callback types 80 */ 81 typedef enum { 82 LIVES_CALLBACK_FRAME_SYNCH = 1, ///< sent when a frame is displayed 83 LIVES_CALLBACK_PLAYBACK_STARTED = 2, ///< sent when a/v playback starts or clip is switched 84 LIVES_CALLBACK_PLAYBACK_STOPPED = 3, ///< sent when a/v playback ends 85 /// sent when a/v playback ends and there is recorded data for 86 /// rendering/previewing 87 LIVES_CALLBACK_PLAYBACK_STOPPED_RD = 4, 88 89 LIVES_CALLBACK_RECORD_STARTED = 32, ///< sent when record starts (TODO) 90 LIVES_CALLBACK_RECORD_STOPPED = 33, ///< sent when record stops (TODO) 91 92 LIVES_CALLBACK_APP_QUIT = 64, ///< sent when app quits 93 94 LIVES_CALLBACK_CLIP_OPENED = 128, ///< sent after a clip is opened 95 LIVES_CALLBACK_CLIP_CLOSED = 129, ///< sent after a clip is closed 96 97 98 LIVES_CALLBACK_CLIPSET_OPENED = 256, ///< sent after a clip set is opened 99 LIVES_CALLBACK_CLIPSET_SAVED = 257, ///< sent after a clip set is closed 100 101 LIVES_CALLBACK_MODE_CHANGED = 4096, ///< sent when interface mode changes 102 103 LIVES_CALLBACK_OBJECT_DESTROYED = 16384, ///< sent when livesApp object is deleted 104 105 #ifndef DOXYGEN_SKIP 106 LIVES_CALLBACK_PRIVATE = 32768 ///< for internal use 107 #endif 108 } lives_callback_t; 109 110 111 /** 112 Character encoding types 113 */ 114 typedef enum { 115 LIVES_CHAR_ENCODING_UTF8, ///< UTF-8 char encoding 116 LIVES_CHAR_ENCODING_LOCAL8BIT, ///< 8 bit locale file encoding 117 LIVES_CHAR_ENCODING_FILESYSTEM, ///< file system encoding (UTF-8 on windows, local8bit on others) 118 //LIVES_CHAR_ENCODING_UTF16, ///< UTF-16 char encoding 119 } lives_char_encoding_t; 120 121 /** 122 Default character encoding 123 */ 124 #define LIVES_CHAR_ENCODING_DEFAULT LIVES_CHAR_ENCODING_UTF8 125 126 /** 127 Dialog response values 128 */ 129 typedef enum { 130 // positive values for custom responses 131 LIVES_DIALOG_RESPONSE_INVALID = -1, ///< INVALID response 132 LIVES_DIALOG_RESPONSE_NONE = 0, ///< Response not obtained 133 LIVES_DIALOG_RESPONSE_OK, ///< OK button clicked 134 LIVES_DIALOG_RESPONSE_RETRY, ///< Retry button clicked 135 LIVES_DIALOG_RESPONSE_ABORT, ///< Abort button clicked 136 LIVES_DIALOG_RESPONSE_RESET, ///< Reset button clicked 137 LIVES_DIALOG_RESPONSE_SHOW_DETAILS, ///< Show details button clicked 138 LIVES_DIALOG_RESPONSE_CANCEL, ///< Cancel button clicked 139 LIVES_DIALOG_RESPONSE_ACCEPT, ///< Accept button clicked 140 LIVES_DIALOG_RESPONSE_YES, ///< Yes button clicked 141 LIVES_DIALOG_RESPONSE_NO ///< No button clicked 142 } lives_dialog_response_t; 143 144 145 /** 146 Audio sources 147 */ 148 typedef enum { 149 LIVES_AUDIO_SOURCE_UNKNOWN = -1, ///< Unknown / invalid 150 LIVES_AUDIO_SOURCE_INTERNAL, ///< Audio source is internal to LiVES 151 LIVES_AUDIO_SOURCE_EXTERNAL ///< Audio source is external to LiVES 152 } lives_audio_source_t; 153 154 155 /** 156 Audio players 157 */ 158 typedef enum { 159 LIVES_AUDIO_PLAYER_UNKNOWN = -1, ///< Unknown / invalid 160 LIVES_AUDIO_PLAYER_PULSE, ///< Audio playback is through PulseAudio 161 LIVES_AUDIO_PLAYER_JACK, ///< Audio playback is thorugh Jack 162 LIVES_AUDIO_PLAYER_SOX, ///< Audio playback is through Sox 163 LIVES_AUDIO_PLAYER_MPLAYER, ///< Audio playback is through mplayer 164 LIVES_AUDIO_PLAYER_MPLAYER2 ///< Audio playback is through mplayer2 165 } lives_audio_player_t; 166 167 168 /** 169 Multitrack insert modes 170 */ 171 typedef enum { 172 LIVES_INSERT_MODE_NORMAL 173 } lives_insert_mode_t; 174 175 176 /** 177 Multitrack gravity 178 */ 179 typedef enum { 180 LIVES_GRAVITY_NORMAL, ///< no gravity 181 LIVES_GRAVITY_LEFT, ///< inserted blocks gravitate to the left 182 LIVES_GRAVITY_RIGHT ///< inserted blocks gravitate to the right 183 } lives_gravity_t; 184 185 186 /** 187 Player looping modes (bitmap) 188 */ 189 typedef enum { 190 LIVES_LOOP_MODE_NONE = 0, ///< no looping 191 LIVES_LOOP_MODE_CONTINUOUS = 1, ///< both video and audio loop continuously 192 LIVES_LOOP_MODE_FIT_AUDIO = 2 ///< video keeps looping until audio playback finishes 193 } lives_loop_mode_t; 194 195 196 //////////////////////////////////////////////////////////////////////////////////////////////////////////////// 197 198 #ifdef __cplusplus 199 200 #include <vector> 201 #include <list> 202 #include <map> 203 204 #include <inttypes.h> 205 206 #include <string> 207 208 /** 209 typedef 210 */ 211 typedef unsigned long ulong; 212 213 214 #ifndef DOXYGEN_SKIP 215 extern "C" { 216 void binding_cb(lives_callback_t cb_type, const char *msgstring, uint64_t id); 217 } 218 #endif 219 220 using namespace std; 221 222 ///////////////////////////////////////////////////////////////////////////////////////////////////// 223 224 225 /** 226 lives namespace. 227 */ 228 namespace lives { 229 230 //////////////////////////////////////////////////// 231 232 /** 233 typedef 234 */ 235 typedef class livesApp livesApp; 236 237 /** 238 typedef 239 */ 240 typedef class set set; 241 242 /** 243 typedef 244 */ 245 typedef class clip clip; 246 247 /** 248 typedef 249 */ 250 typedef class effectKey effectKey; 251 252 /** 253 typedef 254 */ 255 typedef class effectKeyMap effectKeyMap; 256 257 /** 258 typedef 259 */ 260 typedef class effect effect; 261 262 263 /** 264 typedef 265 */ 266 typedef class player player; 267 268 269 /** 270 typedef 271 */ 272 typedef class multitrack multitrack; 273 274 275 /** 276 typedef 277 */ 278 typedef class block block; 279 280 281 /** 282 typedef 283 */ 284 typedef class livesString livesString; 285 286 287 /** 288 typedef 289 */ 290 typedef list<livesString> livesStringList; 291 292 293 /////////////////////////////////////////////////// 294 295 296 /** 297 class "livesString". 298 A subclass of std::string which automatically handles various character encodings. 299 */ 300 class livesString : public std::string { 301 public: livesString(const string & str="",lives_char_encoding_t e=LIVES_CHAR_ENCODING_DEFAULT)302 livesString(const string &str = "", lives_char_encoding_t e = LIVES_CHAR_ENCODING_DEFAULT) : std::string(str), m_encoding(e) {} livesString(const string & str,size_t pos,size_t len=npos,lives_char_encoding_t e=LIVES_CHAR_ENCODING_DEFAULT)303 livesString(const string &str, size_t pos, size_t len = npos, 304 lives_char_encoding_t e = LIVES_CHAR_ENCODING_DEFAULT) : std::string(str, pos, 305 len), m_encoding(e) {} livesString(const char * s,lives_char_encoding_t e=LIVES_CHAR_ENCODING_DEFAULT)306 livesString(const char *s, lives_char_encoding_t e = LIVES_CHAR_ENCODING_DEFAULT) : std::string(s), m_encoding(e) {} livesString(const char * s,size_t n,lives_char_encoding_t e=LIVES_CHAR_ENCODING_DEFAULT)307 livesString(const char *s, size_t n, lives_char_encoding_t e = LIVES_CHAR_ENCODING_DEFAULT) : std::string(s, n), 308 m_encoding(e) {} livesString(size_t n,char c,lives_char_encoding_t e=LIVES_CHAR_ENCODING_DEFAULT)309 livesString(size_t n, char c, lives_char_encoding_t e = LIVES_CHAR_ENCODING_DEFAULT) : std::string(n, c), m_encoding(e) {} 310 template <class InputIterator> livesString(InputIterator first,InputIterator last,lives_char_encoding_t e=LIVES_CHAR_ENCODING_DEFAULT)311 livesString(InputIterator first, InputIterator last, 312 lives_char_encoding_t e = LIVES_CHAR_ENCODING_DEFAULT) : std::string(first, last), m_encoding(e) {} 313 314 /** 315 Change the character encoding of the string. 316 @param enc the character encoding to convert to. 317 @return either the same string if no conversion is needed, or a new string if conversion is needed 318 */ 319 livesString toEncoding(lives_char_encoding_t enc); 320 321 /** 322 Define the character encoding of the string. 323 @param enc the character encoding the string is in. 324 */ 325 void setEncoding(lives_char_encoding_t enc); 326 327 /** 328 Return the encoding that the string was declared as. 329 @return the character encoding the string is in. 330 */ 331 lives_char_encoding_t encoding(); 332 333 private: 334 lives_char_encoding_t m_encoding; 335 }; 336 337 #ifndef DOXYGEN_SKIP 338 typedef void *(*callback_f)(void *); 339 340 typedef struct { 341 ulong id; 342 livesApp *object; 343 lives_callback_t cb_type; 344 callback_f func; 345 void *data; 346 } closure; 347 348 typedef list<closure *> closureList; 349 typedef list<closure *>::iterator closureListIterator; 350 #endif 351 352 /** 353 Struct passed to modeChanged callback. 354 */ 355 typedef struct { 356 lives_interface_mode_t mode; ///< mode changed to 357 } modeChangedInfo; 358 359 360 /** 361 Struct passed to appQuit callback. 362 */ 363 typedef struct { 364 int signum; ///< signal which caused the app to exit, or 0 if the user or script quit normally. 365 } appQuitInfo; 366 367 368 #ifndef DOXYGEN_SKIP 369 typedef struct { 370 ulong id; 371 char *response; 372 } _privateInfo; 373 374 375 typedef bool (*private_callback_f)(_privateInfo *, void *); 376 #endif 377 378 /** 379 Type of callback function for LIVES_CALLBACK_MODE_CHANGED. 380 @see LIVES_CALLBACK_MODE_CHANGED 381 @see livesApp::addCallback(lives_callback_t cb_type, modeChanged_callback_f func, void *data) 382 */ 383 typedef bool (*modeChanged_callback_f)(livesApp *, modeChangedInfo *, void *); 384 385 /** 386 Type of callback function for LIVES_CALLBACK_APP_QUIT. 387 @see LIVES_CALLBACK_APP_QUIT 388 @see livesApp::addCallback(lives_callback_t cb_type, appQuit_callback_f func, void *data) 389 */ 390 typedef bool (*appQuit_callback_f)(livesApp *, appQuitInfo *, void *); 391 392 393 /** 394 Type of callback function for LIVES_CALLBACK_OBJECT_DESTROYED. 395 @see LIVES_CALLBACK_OBJECT_DESTROYED 396 @see livesApp::addCallback(lives_callback_t cb_type, objectDestroyed_callback_f func, void *data) 397 */ 398 typedef bool (*objectDestroyed_callback_f)(livesApp *, void *); 399 400 401 /** 402 class "livesApp". 403 Represents a single LiVES application. Note that currently only one such instance can be valid at a time, 404 attempting to create a second concurrent instance will return an invalid instance. 405 */ 406 class livesApp { 407 friend set; 408 friend clip; 409 friend effectKeyMap; 410 friend effectKey; 411 friend player; 412 friend multitrack; 413 friend block; 414 415 public: 416 /** 417 Constructor with no arguments. 418 */ 419 livesApp(); 420 421 /** 422 Constructor with argc, argv arguments. 423 argv array is equivalent to commandline options passed to the LiVES application. 424 @param argc count of number of arguments 425 @param argv[] array of options. 426 */ 427 livesApp(int argc, char *argv[]); 428 429 /** 430 Destructor: closes the LiVES application. 431 Deletes any callbacks which were set for this instance. 432 */ 433 ~livesApp(); 434 435 /** 436 Returns whether the instance is valid or not. 437 A valid instance is connected to a running LiVES application. 438 @return true if instance is connected to a running LiVES application. 439 */ 440 bool isValid() const; 441 442 /** 443 @return true if status() == LIVES_STATUS_READY. 444 @see status(). 445 */ 446 bool isReady() const; 447 448 /** 449 Equivalent to status() == LIVES_STATUS_PLAYING. 450 @return true if status() == LIVES_STATUS_PLAYING. 451 @see status(). 452 */ 453 bool isPlaying() const; 454 455 /** 456 @return the current set. 457 */ 458 const set &getSet(); 459 460 /** 461 @return the current effectKeyMap. 462 */ 463 const effectKeyMap &getEffectKeyMap(); 464 465 /** 466 @return the player for this livesApp. 467 */ 468 const player &getPlayer(); 469 470 /** 471 @return the multitrack object for this livesApp. 472 */ 473 const multitrack &getMultitrack(); 474 475 /** 476 Remove a previously added callback. 477 @param id value previously returned from addCallback. 478 @return true if playback was stopped. 479 */ 480 bool removeCallback(ulong id) const; 481 482 /** 483 Add a modeChanged callback. 484 @param cb_type must have value LIVES_CALLBACK_MODE_CHANGED. 485 @param func function to be called when this signal is received. 486 @param data data to be passed to callback function 487 @return unsigned long callback_id 488 @see LIVES_CALLBACK_MODE_CHANGED 489 @see removeCallback(). 490 */ 491 ulong addCallback(lives_callback_t cb_type, modeChanged_callback_f func, void *data) const; 492 493 /** 494 Add an appQuit callback. 495 @param cb_type must have value LIVES_CALLBACK_APP_QUIT 496 @param func function to be called when this signal is received. 497 @param data data to be passed to callback function 498 @return unsigned long callback_id 499 @see LIVES_CALLBACK_APP_QUIT 500 @see removeCallback(). 501 */ 502 ulong addCallback(lives_callback_t cb_type, appQuit_callback_f func, void *data) const; 503 504 /** 505 Add an objectDestroyed callback. 506 @param cb_type must have value LIVES_CALLBACK_OBJECT_DESTROYED 507 @param func function to be called when this signal is received. 508 @param data data to be passed to callback function 509 @return unsigned long callback_id 510 @see LIVES_CALLBACK_OBJECT_DESTROYED 511 @see removeCallback(). 512 */ 513 ulong addCallback(lives_callback_t cb_type, objectDestroyed_callback_f func, void *data) const; 514 515 /** 516 Show Info dialog in the LiVES GUI. 517 Only has an effect when status() is LIVES_STATUS_READY. 518 @param text text to be diaplayed in the dialog. 519 @param blocking if true then function will block until the user presses "OK" 520 @return if blocking, returns the response code from the dialog. 521 */ 522 lives_dialog_response_t showInfo(livesString text, bool blocking = true); 523 524 /** 525 Allow the user choose a file via a fileselector. 526 Only has an effect when status() is LIVES_STATUS_READY, otherwise returns an empty livesString. 527 After returning, the setting that the user selected for deinterlace may be obtained by calling 528 deinterlaceOption(). This value can the be passed into openFile(). 529 Chooser type will direct the user towards the type of file to choose, however there is no guarantee 530 that a file of the "correct" type will be returned. If the user cancels then an empty livesString will be returned. 531 @param dirname directory name to start in (or NULL) 532 @param chooser_type must be either LIVES_FILE_CHOOSER_VIDEO_AUDIO or LIVES_FILE_CHOOSER_AUDIO_ONLY. 533 @param title title of window to display, or NULL to use a default title. 534 @return the name of the file selected. 535 @see openFile(). 536 */ 537 livesString chooseFileWithPreview(livesString dirname, lives_filechooser_t chooser_type, livesString title = livesString("")); 538 539 /** 540 Open a file and return a clip for it. 541 Only works when status() is LIVES_STATUS_READY, otherwise an invalid clip is returned. 542 If the file pointed to cannot be opened as a clip, an invalid clip is returned. 543 If interactive() is true, the user may cancel the load, or choose to load only part of the file. 544 @param fname the full pathname of the file to open 545 @param with_audio if true the audio will be loaded as well as the video 546 @param stime the time in seconds from which to start loading 547 @param frames number of frames to open (0 means all frames) 548 @param deinterlace set to true to force deinterlacing 549 @return a clip. 550 @see chooseFileWithPreview(). 551 @see deinterlaceOption(). 552 */ 553 clip openFile(livesString fname, bool with_audio = true, double stime = 0., int frames = 0, bool deinterlace = false); 554 555 /** 556 Returns a list of available sets. The list returned depends on the setting of prefs::tmpDir(). 557 This may be an expensive operation as it requires accessing the underlying filesystem. 558 If the set is invalid, an empty livesStringList is returned. 559 @return a list<livesString> of set names. 560 @see reloadSet(). 561 @see set::save(). 562 */ 563 livesStringList availableSets(); 564 565 /** 566 Allow the user to choose a set to open. 567 Only has an effect when status() is LIVES_STATUS_READY, and there are no currently open clips, 568 otherwise returns an empty livesString. 569 If the user cancels, an empty livesString is returned. 570 The valid list of sets to choose from will be equivalent to the list returned by availableSets(). 571 @return the name of the set selected. 572 @see reloadSet(). 573 @see availableSets(). 574 */ 575 livesString chooseSet(); 576 577 /** 578 Reload an existing clip set. 579 Only works when status() is LIVES_STATUS_READY, otherwise false is returned. 580 A set may not be accessed concurrently by more than one copy of LiVES. 581 The valid list of sets is equivalent to the list returned by availableSets(). 582 If setname is an empty livesString, chooseSet() will be called first to get a set name. 583 @param setname the name of the set to reload. 584 @see chooseSet(). 585 @see availableSets(). 586 */ 587 bool reloadSet(livesString setname); 588 589 /** 590 Change the interactivity of the GUI application. 591 Interactivity is via menus and keyboard accelerators 592 @param setting set to true to allow interaction with the GUI. 593 @return the new setting. 594 @see interactive(). 595 */ 596 bool setInteractive(bool setting); 597 598 /** 599 Returns whether the GUI app is in interactive mode. 600 @return true if GUI interactivity via menus and keyboard accelerators is enabled. 601 @see setInteractive(). 602 */ 603 bool interactive(); 604 605 /** 606 Returns last setting of deinterlace by user. 607 @return value that the user selected during the last filechooser with preview operation. 608 This value may be passed into openFile(). 609 @see openFile(). 610 */ 611 bool deinterlaceOption(); 612 613 /** 614 Get the current interface mode of the livesApp. 615 If the livesApp is invalid, returns LIVES_INTERFACE_MODE_INVALID. 616 @return current mode. 617 @see setMode(). 618 */ 619 lives_interface_mode_t mode(); 620 621 /** 622 Set the current interface mode of the livesApp. 623 Only works if status() is LIVES_STATUS_READY. 624 If the livesApp is invalid, returns LIVES_INTERFACE_MODE_INVALID. 625 @param mode the interface mode to set to 626 @return the new interface mode. 627 @see mode(). 628 */ 629 lives_interface_mode_t setMode(lives_interface_mode_t mode);//, livesMultitrackSettings settings=NULL); 630 631 /** 632 Get the current operational status of the livesApp. 633 @return current status. 634 @see isReady(). 635 @see isPlaying(). 636 */ 637 lives_status_t status() const; 638 639 /** 640 If status() is LIVES_STATUS_PROCESSING, cancel the current processing if possible. 641 @return true if the processing was cancelled. 642 */ 643 bool cancel(); 644 645 646 647 #ifndef DOXYGEN_SKIP 648 // For internal use only. 649 closureList &closures(); 650 void invalidate(); 651 void setClosures(closureList cl); 652 653 bool setPref(const char *prefidx, bool val) const; 654 bool setPref(const char *prefidx, int val) const; 655 bool setPref(const char *prefidx, int bitfield, bool val) const; 656 657 #endif 658 659 protected: 660 ulong addCallback(lives_callback_t cb_type, private_callback_f func, void *data) const; 661 662 private: 663 ulong m_id; 664 closureList m_closures; 665 set *m_set; 666 player *m_player; 667 effectKeyMap *m_effectKeyMap; 668 multitrack *m_multitrack; 669 670 pthread_t *m_thread; 671 672 bool m_deinterlace; 673 674 ulong appendClosure(lives_callback_t cb_type, callback_f func, void *data) const; 675 void init(int argc, char *argv[]); 676 677 void operator=(livesApp const &); // Don't implement 678 livesApp(const livesApp &other); // Don't implement 679 680 }; 681 682 683 684 /** 685 class "clip". 686 Represents a clip which is open in LiVES. 687 @see set::nthClip() 688 @see livesApp::openFile() 689 @see player::foregroundClip() 690 @see player::backgroundClip() 691 */ 692 class clip { 693 friend livesApp; 694 friend set; 695 friend block; 696 friend multitrack; 697 friend player; 698 699 public: 700 701 /** 702 Creates a new, invalid clip 703 */ 704 clip(); 705 706 /** 707 Check if clip is valid. 708 A clip is valid if it is loaded in a valid livesApp instance, and the livesApp::status() is not LIVES_STATUS_NOTREADY. 709 @see livesApp::openFile(). 710 @return true if the clip is valid. 711 */ 712 bool isValid() const; 713 714 /** 715 Number of frames in this clip. 716 If the clip is audio only, 0 is returned. 717 If clip is not valid then 0 is returned. 718 @return int number of frames, or 0 if clip is not valid. 719 */ 720 int frames(); 721 722 /** 723 Width of the clip in pixels. 724 If the clip is audio only, 0 is returned. 725 If clip is not valid then 0 is returned. 726 @return int width in pixels, or 0 if clip is not valid. 727 */ 728 int width(); 729 730 /** 731 Height of the clip in pixels. 732 If the clip is audio only, 0 is returned. 733 If clip is not valid then 0 is returned. 734 @return int height in pixels, or 0 if clip is not valid. 735 */ 736 int height(); 737 738 /** 739 Framerate (frames per second) of the clip. 740 If the clip is audio only, 0.0 is returned. 741 If clip is not valid then 0.0 is returned. 742 @return double framerate of the clip, or 0.0 if clip is not valid. 743 */ 744 double FPS(); 745 746 /** 747 Framerate (frames per second) that the clip is/will be played back at. 748 This may vary from the normal FPS(). During playback it will be equivalent to player::FPS(). 749 If livesApp::mode() is LIVES_INTERFACE_MODE_MULTITRACK then this will return multitrack::FPS(). 750 IF the clip is invalid, 0. is returned. 751 @return the playback framerate 752 @see player::setCurrentFPS(). 753 @see player::FPS(). 754 */ 755 double playbackFPS(); 756 757 /** 758 Human readable name of the clip. 759 If clip is not valid then empty livesString is returned. 760 @return livesString name, or empty livesString if clip is not valid. 761 */ 762 livesString name(); 763 764 /** 765 Audio rate for this clip. 766 If the clip is video only, 0 is returned. 767 If clip is not valid then 0 is returned. 768 Note this is not necessarily the same as the soundcard audio rate which can be obtained via prefs::audioPlayerRate(). 769 @return int audio rate, or 0 if clip is not valid. 770 @see playbackAudioRate() 771 */ 772 int audioRate(); 773 774 /** 775 The current playback audio rate for this clip, which may differ from audioRate(). 776 If the clip is video only, 0 is returned. 777 If clip is not valid then 0 is returned. 778 Note this is not necessarily the same as the soundcard audio rate which can be obtained via prefs::audioPlayerRate(). 779 If livesApp::mode() is LIVES_INTERFACE_MODE_MULTITRACK then this will return multitrack::audioRate(). 780 @return int playback audio rate, or 0 if clip is not valid. 781 @see audiorate(). 782 */ 783 int playbackAudioRate(); 784 785 /** 786 Number of audio channels (eg. left, right) for this clip. 787 If the clip is video only, 0 is returned. 788 If clip is not valid then 0 is returned. 789 @return int audio channels, or 0 if clip is not valid. 790 */ 791 int audioChannels(); 792 793 /** 794 Size in bits of audio samples (eg. 8, 16, 32) for this clip. 795 If the clip is video only, 0 is returned. 796 If clip is not valid then 0 is returned. 797 @return int audio sample size, or 0 if clip is not valid. 798 */ 799 int audioSampleSize(); 800 801 /** 802 Returns whether the audio is signed (true) or unsigned (false). 803 If clip is video only or not valid then the return value is undefined. 804 @return bool audio signed. 805 */ 806 bool audioSigned(); 807 808 /** 809 Returns the endianness of the audio. 810 If clip is video only or not valid then the return value is undefined. 811 @return bool audio signed. 812 */ 813 lives_endian_t audioEndian(); 814 815 816 /** 817 Returns the length in seconds for audio in the clip 818 If the clip is invalid, returns 0. 819 @return the length of the clip audio, in seconds. 820 */ 821 double audioLength(); 822 823 /** 824 Start of the selected frame region. 825 If the clip is audio only, 0 is returned. 826 If clip is not valid then 0 is returned. 827 @return int frame selection start, or 0 if clip is not valid. 828 */ 829 int selectionStart(); 830 831 /** 832 End of the selected frame region. 833 If the clip is audio only, 0 is returned. 834 If clip is not valid then 0 is returned. 835 @return int frame selection end, or 0 if clip is not valid. 836 */ 837 int selectionEnd(); 838 839 840 /** 841 Select all frames in the clip. if the clip is invalid does nothing. 842 Only works is livesApp::status() is LIVES_STATUS_READY or LIVES_STATUS_PLAYING. 843 @return true if the operation was successful. 844 */ 845 bool selectAll(); 846 847 /** 848 Set the selection start frame for the clip. If the new start is > selectionEnd() then selection end will be set to the new start. 849 If the clip is invalid there is no effect. 850 Only functions if livesApp::status() is LIVES_STATUS_READY or LIVES_STATUS_PLAYING. 851 @param start the selection start frame which must be in range 1 <= start <= frames(). 852 @see setSelectionEnd(). 853 */ 854 bool setSelectionStart(unsigned int start); 855 856 /** 857 Set the selection end frame for the clip. If the new end is < selectionStart() then selection start will be set to the new end. 858 If the clip is invalid there is no effect. 859 Only functions if livesApp::status() is LIVES_STATUS_READY or LIVES_STATUS_PLAYING. 860 @param end the selection end frame which must be in range 1 <= end <= frames(). 861 @see setSelectionStart(). 862 */ 863 bool setSelectionEnd(unsigned int end); 864 865 /** 866 Switch to this clip as the current foreground clip. 867 Only works if livesApp::status() is LIVES_STATUS_READY or LIVES_STATUS_PLAYING and livesApp::mode() is LIVES_INTERFACE_MODE_CLIP_EDITOR. 868 If clips are switched during playback, the application acts as if livesApp::loopMode() were set to LIVES_LOOP_MODE_CONTINUOUS. 869 If the clip is invalid, nothing happens and false is returned. 870 @return true if the switch was successful. 871 @see player::setForegroundClip() 872 */ 873 bool switchTo(); 874 875 /** 876 Switch to this clip as the current background clip. 877 Only works if livesApp::status() is LIVES_STATUS_READY or LIVES_STATUS_PLAYING and livesApp::mode() is LIVES_INTERFACE_MODE_CLIP_EDITOR. 878 If the clip is invalid, nothing happens and false is returned. 879 @return true if the switch was successful. 880 @see player::setBackgroundClip() 881 */ 882 bool setIsBackground(); 883 884 /** 885 @return true if the two clips have the same internal id, and belong to the same livesApp. 886 */ operator ==(const clip & other)887 inline bool operator==(const clip &other) { 888 return other.m_uid == m_uid && m_lives == other.m_lives; 889 } 890 891 protected: 892 clip(ulong uid, livesApp *lives = NULL); 893 ulong m_uid; 894 895 private: 896 livesApp *m_lives; 897 898 }; 899 900 901 902 #ifndef DOXYGEN_SKIP 903 typedef vector<ulong> clipList; 904 typedef vector<ulong>::iterator clipListIterator; 905 #endif 906 907 ///// set //////// 908 909 910 /** 911 class "set". 912 Represents a list of clips and/or layouts which are open in LiVES. May be obtained from livesApp::getSet(). 913 @see livesApp::getSet() 914 */ 915 class set { 916 friend livesApp; 917 918 public: 919 920 /** 921 Returns whether the set is valid or not. 922 The set is valid if belongs to a valid livesApp, and the livesApp::status() is not LIVES_STATUS_NOTREADY. 923 @return true if the set is valid (associated with a valid livesApp instance). 924 */ 925 bool isValid() const; 926 927 /** 928 Returns the current name of the set. 929 If it has not been defined, an empty livesString is returned. If the set is invalid, an empty livesString is returned. 930 @return livesString name. 931 */ 932 livesString name() const; 933 934 /** 935 Set the name of the current set. Only works if there are clips loaded, and the livesApp::status() is LIVES_STATUS_READY. 936 Can only be done if the current set has no name. You need to do this before saving a layout if the current set has no name. 937 If name is an empty string, the user can choose the name at runtime. If livesApp::interactive() is false, the user can cancel. 938 Valid set names may not be empty, begin with a "." or contain spaces or the characters / \ * or ". The set name must not be in use by 939 another copy of LiVES. The maximum length of a set name is 128 characters. 940 @param name the name of the set 941 @return true if the name was set. 942 @see name(). 943 */ 944 bool setName(livesString name = livesString()) const; 945 946 /** 947 Save the set, and close all open clips and layouts. 948 If the set name is empty, the user can choose the name via the GUI. If livesApp::interactive() is false, the user may not cancel. 949 If the name is defined, and it points to a different, existing set, the set will not be saved and false will be returned, 950 unless force_append is set to true, in which case the current clips and layouts will be appended to the other set. 951 Saving a set with a new name is an expensive operation as it requires moving files in the underlying filesystem. 952 See setName() for the rules on valid set names. 953 @param name name to save set as, or empty livesString to let the user choose a name. 954 @param force_append set to true to force appending to another existing set. 955 @return true if the set was saved. 956 */ 957 bool save(livesString name, bool force_append = false) const; 958 959 /** 960 Save the set, and close all open clips and layouts. 961 The current set name() is used. If the set name is not defined, the user will be prompted to enter it at runtime. 962 @return true if the set was saved. 963 */ 964 bool save() const; 965 966 /** 967 Returns the number of clips in the set. If the set is invalid, returns 0. 968 @return number of clips. 969 @see indexOf(). 970 @see nthClip(). 971 */ 972 unsigned int numClips() const; 973 974 /** 975 Returns the nth clip in the set. If n >= numClips(), returns an invalid clip. If the set is invalid, returns an invalid clip. 976 @return the nth clip in the set. 977 @see indexOf(). 978 @see numClips(). 979 */ 980 clip nthClip(unsigned int n) const; 981 982 /** 983 Returns the index of a clip in the currentSet. If the clip is not in the current set, then -1 is returned. 984 If the set is invalid or the clip is invalid, returns -1. 985 @return the index of the clip in the set. 986 @see nthClip(). 987 @see numClips(). 988 */ 989 int indexOf(clip c) const; 990 991 /** 992 Returns a list of layout names for this set. If the set is invalid, returns an empty livesStringList. 993 @return a list of layout names for this set. 994 @see livesApp::reloadLayout(). 995 */ 996 livesStringList layoutNames(unsigned int n) const; 997 998 /** 999 @return true if the two sets belong to the same livesApp. 1000 */ operator ==(const set & other) const1001 inline bool operator==(const set &other) const { 1002 return other.m_lives == m_lives; 1003 } 1004 1005 1006 protected: 1007 set(livesApp *lives = NULL); 1008 1009 private: 1010 livesApp *m_lives; 1011 clipList m_clips; 1012 1013 void update_clip_list(void); 1014 1015 1016 }; 1017 1018 1019 1020 1021 1022 /** 1023 class "player". 1024 Represents a media player associated with a livesApp. 1025 @see livesApp::getPlayer() 1026 */ 1027 class player { 1028 friend livesApp; 1029 1030 public: 1031 1032 /** 1033 Returns whether the player is valid or not. 1034 A valid player belongs to a valid livesApp, and the livesApp::status() is not LIVES_STATUS_NOTREADY. 1035 @return true if the player is valid. 1036 */ 1037 bool isValid() const; 1038 1039 /** 1040 @return true if the livesApp::status() is LIVES_STATUS_PLAYING. 1041 */ 1042 bool isPlaying() const; 1043 1044 1045 /** 1046 @return true if the player is set to record. Recording will only actually occur if isPlaying() is also true. 1047 */ 1048 bool isRecording() const; 1049 1050 /** 1051 Set playback in a detached window. 1052 If the livesApp::mode() is LIVES_INTERFACE_MODE_CLIPEDIT and prefs::sepWinSticky() is true, the window appears straight away; 1053 otherwise it appears only when isPlaying() is true. 1054 @param setting the value to set to 1055 @see setFS(). 1056 @see sepWin(). 1057 */ 1058 void setSepWin(bool setting) const; 1059 1060 /** 1061 @return true if playback is in a separate window from the main GUI. 1062 @see setSepWin(). 1063 */ 1064 bool sepWin() const; 1065 1066 /** 1067 Set playback fullscreen. Use of setFS() is recommended instead. 1068 @param setting the value to set to 1069 @see setFS(). 1070 @see fullScreen(). 1071 */ 1072 void setFullScreen(bool setting) const; 1073 1074 /** 1075 @return true if playback is full screen. 1076 @see setFullScreen(). 1077 */ 1078 bool fullScreen() const; 1079 1080 /** 1081 Combines the functionality of setSepWin() and setFullScreen(). 1082 If the livesApp::mode() is LIVES_INTERFACE_MODE_CLIPEDIT and prefs::sepWinSticky() is true, the window appears straight away, 1083 but it will only fill the screen when isPlaying() is true; otherwise it appears only when isPlaying() is true. 1084 @param setting the value to set to 1085 @see setSepWin() 1086 @see setFullScreen() 1087 */ 1088 void setFS(bool setting) const; 1089 1090 /** 1091 Commence playback of video and audio with the currently selected clip. 1092 Only has an effect when livesApp::status() is LIVES_STATUS_READY. 1093 @return true if playback was started. 1094 */ 1095 bool play() const; 1096 1097 /** 1098 Stop playback. 1099 If livesApp::status() is not LIVES_STATUS_PLAYING, nothing happens. 1100 @return true if playback was stopped. 1101 */ 1102 bool stop() const; 1103 1104 /** 1105 Set the foreground clip for the player. Equivalent to clip::switchTo() except that it only functions when 1106 livesApp::status() is LIVES_STATUS_PLAYING and the livesApp::mode() is LIVES_INTERFACE_MODE_CLIPEDIT. 1107 If the clip is invalid, or isActive() is false, nothing happens and false is returned. 1108 @param c the clip to set as foreground. 1109 @return true if the function was successful. 1110 @see foregroundClip(). 1111 @see setBackgroundClip(). 1112 */ 1113 bool setForegroundClip(clip c) const; 1114 1115 /** 1116 Returns the current foreground clip of the player. If isActive() is false, returns an invalid clip. 1117 If the livesApp::mode() is not LIVES_INTERFACE_MODE_CLIPEDIT, returns an invalid clip. 1118 @return the current foreground clip. 1119 @see setForegroundClip(). 1120 @see backgroundClip(). 1121 */ 1122 clip foregroundClip() const; 1123 1124 /** 1125 Set the background clip for the player. Equivalent to clip::setIsBackground() except that it only functions when 1126 livesApp::status() is LIVES_STATUS_PLAYING and the livesApp::mode() is LIVES_INTERFACE_MODE_CLIPEDIT. 1127 Only works if there is one or more transition effects active. 1128 If the clip is invalid, or isActive() is false, nothing happens and false is returned. 1129 @return true if the function was successful. 1130 @see backgroundClip(). 1131 @see setForegroundClip(). 1132 */ 1133 bool setBackgroundClip(clip c) const; 1134 1135 /** 1136 Returns the current background clip of the player. If isActive() is false, returns an invalid clip. 1137 If the livesApp::mode() is not LIVES_INTERFACE_MODE_CLIPEDIT, returns an invalid clip. 1138 @return the current background clip. 1139 @see setBackgroundClip(). 1140 @see foregroundClip(). 1141 */ 1142 clip backgroundClip() const; 1143 1144 /** 1145 Set the current playback start time in seconds (this is also the insertion point in multitrack mode). 1146 Only works if the livesApp::status() is LIVES_STATUS_READY. If livesApp::mode() is LIVES_INTERFACE_MODE_CLIP_EDITOR, 1147 the start time may not be set beyond the end of the current clip (video and audio). 1148 The outcome of setting playback beyond the end of video but not of audio and vice-versa depends on the value of loopMode(). 1149 If livesApp::mode() is LIVES_INTERFACE_MODE_MULITRACK, setting the current time may cause the timeline to stretch visually 1150 (i.e zoom out). 1151 The miminum value is 0.0 in every mode. Values < 0. will be ignored. 1152 If isValid() is false, nothing happens and 0. is returned. 1153 @param time the time in seconds to set playback start time to. 1154 @return the new playback start time. 1155 @see videoPlaybackTime(). 1156 @see multitrack::setCurrentTime(). 1157 */ 1158 double setPlaybackStartTime(double time) const; 1159 1160 /** 1161 Set the video playback frame. Only works if livesApp::status() is LIVES_STATUS_PLAYING and livesApp::mode() is 1162 LIVES_INTERFACE_MODE_CLIPEDIT. 1163 If the frame parameter is < 1 or > foregroundClip().frames() nothing happens. 1164 If background is true, the function sets the frame for backgroundClip(). 1165 If background is false and prefs::audioFollowsFPSChanges() is true, then the audio playback will sync to the new video position. 1166 @param frame the new frame to set to 1167 @param background if true sets the frame for the background clip (if any) 1168 @return the video frame set to, or 0 if the operation is invalid. 1169 @see videoPlaybackTime() 1170 @see setPlaybackTime() 1171 */ 1172 int setVideoPlaybackFrame(int frame, bool background = false) const; 1173 1174 /** 1175 Return the current clip playback time. If livesApp::mode() is LIVES_INTERFACE_MODE_CLIPEDIT, then this returns 1176 the current playback time for video in the current foregroundClip(), or the current backgroundClip() if background is true: 1177 if there is no background clip, 0. is returned. 1178 If livesApp::mode() is LIVES_INTERFACE_MODE_MULTITRACK, then this returns the current player time in the multitrack timeline, 1179 (equivalent to multitrack::currentTime()), and the background parameter is ignored. 1180 This function works if livesApp::status() is LIVES_STATUS_READY or LIVES_STATUS_PLAYING. 1181 If isValid() is false, 0. is returned. 1182 @param background if true returns the playback time for the background clip. 1183 @return the current foreground or background clip playback time. 1184 @see setVideoPlaybackFrame(). 1185 @see audioPlaybackTime(). 1186 @see elapsedTime(). 1187 @see multitrack::currentTime(). 1188 */ 1189 double videoPlaybackTime(bool background = false) const; 1190 1191 /** 1192 Set the audio playback time. Only works if livesApp::status() is LIVES_STATUS_PLAYING and livesApp::mode() is 1193 LIVES_INTERFACE_MODE_CLIPEDIT and prefs::isRealtimeAudioPlayer() is true for prefs::audioPlayer(). 1194 Does not work if prefs::audioSource() is LIVES_AUDIO_SOURCE_INTERNAL and player::recording() is true. 1195 If the time parameter is < 0. or > clip::audioLength() nothing happens. 1196 The time is actually set to the nearest video frame start to the requested time. 1197 @param time the new time to set to 1198 @return the audio playback time, or 0. if the operation is invalid. 1199 @see audioPlaybackTime() 1200 @see setVideoPlaybackFrame() 1201 */ 1202 double setAudioPlaybackTime(double time) const; 1203 1204 /** 1205 Return the current clip audio playback time in seconds. If livesApp::mode() is LIVES_INTERFACE_MODE_CLIPEDIT, then this returns 1206 the current playback time for audio in the current foregroundClip(). 1207 If livesApp::mode() is LIVES_INTERFACE_MODE_MULTITRACK, then this returns the current player time in the multitrack timeline 1208 (equivalent to multitrack::currentTime()). 1209 This function works with livesApp::status() of LIVES_STATUS_READY and LIVES_STATUS_PLAYING. 1210 If isValid() is false, 0. is returned. 1211 If prefs::audioSource() is not LIVES_AUDIO_SOURCE_INTERNAL the value returned is not defined. 1212 @return the current clip audio playback time. 1213 @see videoPlaybackTime(). 1214 @see elapsedTime(). 1215 @see multitrack::currentTime(). 1216 */ 1217 double audioPlaybackTime() const; 1218 1219 /** 1220 Return the elapsed time, i.e. total time in seconds since playback began. 1221 If livesApp::status() is not LIVES_STATUS_PLAYING, 0. is returned. 1222 @return the time in seconds since playback began. 1223 @see playbackTime(). 1224 @see audioPlaybackTime(). 1225 @see multitrack::currentTime(). 1226 */ 1227 double elapsedTime() const; 1228 1229 /** 1230 Set the current playback framerate in frames per second. Only works if livesApp::mode() is LIVES_INTERFACE_MODE_CLIPEDIT and 1231 livesApp::status() is LIVES_STATUS_PLAYING. 1232 Allowed values range from -prefs::maxFPS() to +prefs::maxFPS(). 1233 If prefs::audioFollowsFPSChanges() is true, then the audio playback rate will change proportionally. 1234 If isPlaying() is false, nothing happens and 0. is returned. 1235 Note, the setting only applies to the current clip; if the clip being played is switched then currentFPS() may change. 1236 @param fps the framerate to set 1237 @return the new framerate 1238 @see currentFPS(). 1239 */ 1240 double setCurrentFPS(double fps) const; 1241 1242 /** 1243 Return the current playback framerate in frames per second of the player. 1244 If isValid() is false, returns 0. If livesApp::status is neither LIVES_STATUS_READY nor LIVES_STATUS_PLAYING, returns 0. 1245 Otherwise, this is equivalent to foregroundClip::playbackFPS(). 1246 @return the current or potential playback rate in frames per second. 1247 @see setCurrentFPS(). 1248 @see clip::playbackFPS(). 1249 */ 1250 double currentFPS() const; 1251 1252 /** 1253 Return the current audio rate of the player. 1254 If isValid() is false, returns 0. If livesApp::status is neither LIVES_STATUS_READY nor LIVES_STATUS_PLAYING, returns 0. 1255 Otherwise, this is equivalent to foregroundClip::playbackAudioRate(). 1256 Note this is not necessarily the same as the soundcard audio rate which can be obtained via prefs::audioPlayerRate(). 1257 @return the current or potential audio rate in Hz. 1258 @see clip::playbackAudioRate(). 1259 */ 1260 int currentAudioRate() const; 1261 1262 /** 1263 Set the loop mode for the player. The value is a bitmap, however LIVES_LOOP_MODE_FIT_AUDIO 1264 only has meaning when livesApp::mode() is LIVES_INTERFACE_MODE_CLIPEDIT. 1265 If isValid() is false, nothing happens. 1266 @param mode the desired loop mode 1267 @return the new loop mode 1268 @see loopMode(). 1269 */ 1270 lives_loop_mode_t setLoopMode(lives_loop_mode_t mode) const; 1271 1272 /** 1273 Return the loop mode of the player. 1274 If isValid() is false, returns LIVES_LOOP_MODE_NONE. 1275 @return the current loop mode of the player 1276 @see setLoopMode(). 1277 */ 1278 lives_loop_mode_t loopMode() const; 1279 1280 /** 1281 Set ping pong mode. If pingPong is true then rather than looping forward, video and audio will "bounce" 1282 forwards and backwards off their end points, provided the mode() is LIVES_INTERFACE_MODE_CLIPEDIT. 1283 If mode() is LIVES_INTERFACE_MODE_MULTITRACK, then the value is ignored. 1284 @param setting the desired value 1285 @return the new value 1286 @see pingPong(). 1287 @see loopMode(). 1288 */ 1289 bool setPingPong(bool setting) const; 1290 1291 /** 1292 Return ping pong mode. If pingPong is true then rather than looping forward, video and audio will "bounce" 1293 forwards and backwards off their end points, provided the mode() is LIVES_INTERFACE_MODE_CLIPEDIT. 1294 If mode() is LIVES_INTERFACE_MODE_MULTITRACK, then the value is ignored. 1295 If the player is invalid, false is returned. 1296 @return the current value. 1297 @see setPingPong(). 1298 @see loopMode(). 1299 */ 1300 bool pingPong() const; 1301 1302 /** 1303 Resets the clip::playbackFPS() for the current foreground clip, so it is equal to the clip::FPS(). 1304 Resets the clip::playbackAudioRate so it is equal to the clip::audioRate(). 1305 If possible equalizes the audioPlaybackTime() with the playbackTime() so video and audio are in sync. 1306 Only works if isPlaying() is true. 1307 @return true if the method succeeded. 1308 */ 1309 bool resyncFPS() const; 1310 1311 1312 /** 1313 @return true if the two players belong to the same livesApp. 1314 */ operator ==(const player & other) const1315 inline bool operator==(const player &other) const { 1316 return other.m_lives == m_lives; 1317 } 1318 1319 1320 protected: 1321 player(livesApp *lives = NULL); 1322 1323 private: 1324 livesApp *m_lives; 1325 1326 }; 1327 1328 ///////////////////////////////////////////////////// 1329 1330 /** 1331 class "effectKey". 1332 Represents a single effect key slot. A valid livesApp will have a map of these (effectKeyMapping()) whose size() is equal to 1333 prefs::rteKeysVirtual(). 1334 @see effectKeyMap::operator[] 1335 */ 1336 class effectKey { 1337 friend effectKeyMap; 1338 public: 1339 /** 1340 Creates a new, invalid effect key 1341 */ 1342 effectKey(); 1343 1344 /** 1345 Returns whether the effectKey is valid or not. 1346 An effect key is valid if it is owned by a valid livesApp, and the livesApp::status() is not LIVES_STATUS_NOTREADY, 1347 and the key value is in the range 1 <= key <= prefs::rteKeysVirtual. 1348 @return true if the effectKey is valid. 1349 */ 1350 bool isValid() const; 1351 1352 /** 1353 Return the (physical or virtual) key associated with this effectKey. 1354 Effects (apart from generators) are applied in ascending key order. 1355 Physical keys (1 - 9) can also be toggled from the keyboard by simultaneously holding down the ctrl key, 1356 provided livesApp::interactive() is true. 1357 If the effectKey is invalid, 0 is returned. 1358 @return the physical or virtual key associated with this effectKey. 1359 */ 1360 int key(); 1361 1362 /** 1363 Return the number of modes for this effectKey slot. Modes run from 0 to numModes() - 1. 1364 Effects can be mapped to modes in ascending order, but only one mode is the active mode for the effectKey. 1365 If the effectKey is invalid, 0 will be returned. 1366 @return the number of modes for this effectKey. 1367 */ 1368 int numModes(); 1369 1370 /** 1371 Return the number of mapped modes for this effectKey slot. Modes run from 0 to numModes() - 1. 1372 When numMappedModes() == numModes() for an effectKey, no more effects may be mapped to it until a mapping is erased. 1373 If the effectKey is invalid, 0 will be returned. 1374 @return the number of modes for this effectKey. 1375 */ 1376 int numMappedModes(); 1377 1378 /** 1379 Set the current mode this effectKey. 1380 Only works if the effecKey is valid, a valid effect is mapped to the mode, and livesApp::status() is 1381 LIVES_STATUS_PLAYING or LIVES_STATUS_READY. 1382 @param mode the mode to switch to. 1383 @return the new mode of the effectKey. 1384 @see currentMode(). 1385 @see numMappedModes(). 1386 */ 1387 int setCurrentMode(int mode); 1388 1389 /** 1390 Get the current mode for this effectKey. 1391 If the effectKey is invalid, the current mode is -1. 1392 @return the current mode of the effectKey. 1393 @see setCurrentMode(). 1394 */ 1395 int currentMode(); 1396 1397 /** 1398 Enable an effect mapped to this effectKey, mode(). 1399 Only works if the effecKey is valid, a valid effect is mapped to the mode, and livesApp::status() is 1400 LIVES_STATUS_PLAYING or LIVES_STATUS_READY. 1401 @param setting the value to set to 1402 @return the new state of the effectKey 1403 @see enabled(). 1404 */ 1405 bool setEnabled(bool setting); 1406 1407 /** 1408 Return a value to indicate whether the effect mapped to this effectKey, mode() is active. 1409 If the effectKey is invalid, returns false. 1410 @return true if the effect mapped at mode() is enabled. 1411 @see setEnabled(). 1412 */ 1413 bool enabled(); 1414 1415 /** 1416 Map an effect to the next unused mode for the effectKey. 1417 Will only work if the livesApp::status() is LIVES_STATUS_PLAYING or LIVES_STATUS_READY. 1418 The effectKey and the effect must share the same owner livesApp, and both must be valid. 1419 @param e the effect to append 1420 @return the mode number the effect was mapped to, or -1 if the mapping failed. 1421 @see removeMapping(). 1422 */ 1423 int appendMapping(effect e); 1424 1425 /** 1426 Remove an effect from being mapped to this key. 1427 Will only work if the livesApp::status() is LIVES_STATUS_PLAYING or LIVES_STATUS_READY. 1428 If the effectKey is invalid, or if no effect is mapped to the mode, false is returned and nothing happens. 1429 If an effect is removed, effects mapped to higher mode numbers on the same effectKey will move down a mode to close the gap. 1430 Note: the currentMode() does not change unless this is the last mapped effect for this effectKey, 1431 so this may cause the currently enabled effect to change. 1432 @param mode the mode to remove the effect from. 1433 @return true if an effect was unmapped. 1434 @see appendMapping(). 1435 */ 1436 bool removeMapping(int mode); 1437 1438 /** 1439 Returns the effect mapped to the key at the specified mode. 1440 If the effectKey is invalid, or if no effect is mapped to the mode, an invalid effect is returned. 1441 @param mode the specified mode. 1442 @return the effect mapped to the key at the specified mode. 1443 */ 1444 effect at(int mode); 1445 1446 1447 1448 1449 1450 /** 1451 @return true if the two effectKeys have the same livesApp and key value and belong to the same livesApp 1452 */ operator ==(const effectKey & other)1453 inline bool operator==(const effectKey &other) { 1454 return other.m_key == m_key && m_lives == other.m_lives; 1455 } 1456 1457 protected: 1458 effectKey(livesApp *lives, int key); 1459 1460 private: 1461 int m_key; 1462 livesApp *m_lives; 1463 1464 }; 1465 1466 1467 1468 /** 1469 class "effectKeyMap". 1470 Represents a mapping of effectKey instances to key slots. Real time effects are always applied in order of ascending index value 1471 (with the exception of generator effects, which are applied first). 1472 @see livesApp::getEffectKeyMap() 1473 */ 1474 class effectKeyMap { 1475 friend livesApp; 1476 public: 1477 /** 1478 Returns whether the effectKeyMap is valid or not. 1479 A valid effectKeyMap is owned by a valid livesApp, the livesApp::status() is not LIVES_STATUS_NOTREADY, 1480 and the index is 1 <= i <= prefs::rteKeysVirtual(). 1481 @return true if the effectKeyMap is valid. 1482 */ 1483 bool isValid() const; 1484 1485 /** 1486 Unmap all effects from effectKey mappings, leaving an empty map. 1487 Only has an effect when livesApp::status() is LIVES_STATUS_READY. 1488 @return true if all effects were unmapped 1489 */ 1490 bool clear() const; 1491 1492 /** 1493 Returns the ith effect key for this key map. 1494 Valid range for i is 1 <= i <= prefs::rteKeysVirtual(). 1495 For values of i outside this range, an invalid effectKey is returned. 1496 @param i the index value 1497 @return an effectKey with index i. 1498 @see effectKey::operator[] 1499 */ 1500 effectKey at(int i) const; 1501 1502 /** 1503 Returns the number of key slots (indices) in the effectKeyMap. 1504 The valid range of keys is 1 <= key <= size(). 1505 Equivalent to prefs::rteKeysVirtual(), except that if the effectKeyMap is invalid, returns 0. 1506 @return the number of key slots. 1507 @see prefs::rteKeysVirtual() 1508 */ 1509 size_t size() const; 1510 1511 /** 1512 @return true if the two effectKeyMaps have the same livesApp 1513 */ operator ==(const effectKeyMap & other) const1514 inline bool operator==(const effectKeyMap &other) const { 1515 return other.m_lives == m_lives; 1516 } 1517 1518 /** 1519 Returns an effect key with index i for this key map. The value of i may be chosen freely, but if it is outside the range 1520 1 <= i <= size() then the effectKey will be considered invalid. 1521 @return an effectKey with index i for this key map. 1522 @see at() 1523 */ operator [](int i) const1524 inline effectKey operator [](int i) const { 1525 return effectKey(m_lives, i); 1526 } 1527 1528 1529 protected: 1530 effectKeyMap(livesApp *lives); 1531 1532 private: 1533 livesApp *m_lives; 1534 }; 1535 1536 1537 1538 /** 1539 class "effect". 1540 Represents a single effect. 1541 */ 1542 class effect { 1543 friend effectKey; 1544 friend multitrack; 1545 public: 1546 /** 1547 Create a new effect from a hashname. In case of multiple matches, only the first match is returned. 1548 The hashname should be in utf-8 format, and matching is case insensitive. 1549 In the case of no matches, an invalid effect is returned. 1550 If livesApp::isInvalid() is true, or livesApp::status() is LIVES_STATUS_NOTREADY, an invalid effect will be returned. 1551 Implementation note: we use const livesApp & here to avoid the destructor being called on a copy object, 1552 which would cause LiVES to terminate prematurely. 1553 @param lives a livesApp instance 1554 @param hashname the hashname of an effect, a concatenation of package name, filter name, and if match_full is true, 1555 author and version string. If the filter has "extra_authors" these are also checked. 1556 @param match_full if true then author and version string must match, otherwise only package name and filter name are matched. 1557 If false then the hashname and the target must be equivalent strings. 1558 @return an effect. 1559 */ 1560 effect(const livesApp &lives, livesString hashname, bool match_full = false); 1561 1562 /** 1563 Create a new effect from a template. In case of multiple matches, only the first match is returned. 1564 In the case of no matches, an invalid effect is returned. 1565 LiVESStrings here should be in utf-8 format and matching is case insensitive. 1566 If livesApp::isInvalid() is true, or livesApp::status() is LIVES_STATUS_NOTREADY, an invalid effect will be returned. 1567 Implementation note: we use const livesApp & here to avoid the destructor being called on a copy object, 1568 which would cause LiVES to terminate prematurely. 1569 @param lives a livesApp instance 1570 @param package a package name (e.g. "frei0r", "LADSPA"), or "" to match any package. 1571 @param fxname the name of a filter (e.g. "chroma blend") or "" to match any filter name. 1572 @param author the name of the author of the effect (e.g. "jsmith") or "" to match any author. If the plugin has "extra_authors" 1573 this value is also permitted as a match. 1574 @param version the number of a version to match, or 0 to match any version. 1575 @return an effect. 1576 */ 1577 effect(const livesApp &lives, livesString package, livesString fxname, livesString author = livesString(), int version = 0); 1578 1579 /** 1580 Returns whether the effect is valid or not. 1581 A valid effect is owned by a valid livesApp, whose livesApp::status() is not LIVES_STATUS_NOTREADY, 1582 and which references an existing effect plugin. 1583 @return true if the effect is valid. 1584 */ 1585 bool isValid() const; 1586 1587 /** 1588 @return true if the two effects have the same index and the same livesApp owner 1589 */ operator ==(const effect & other)1590 inline bool operator==(const effect &other) { 1591 return other.m_idx == m_idx && m_lives == other.m_lives; 1592 } 1593 1594 protected: 1595 effect(); 1596 effect(livesApp *m_lives, int idx); 1597 livesApp *m_lives; 1598 int m_idx; 1599 1600 private: 1601 1602 }; 1603 1604 1605 1606 /** 1607 class "block". 1608 Represents a sequence of frames from the same clip on the same track which forms part of a layout. 1609 This is an abstracted level, since layouts are fundamentally formed of "events" which may span multiple tracks. 1610 */ 1611 class block { 1612 friend multitrack; 1613 1614 public: 1615 1616 /** 1617 returns whether the block is valid or not. A block may become invalid if it is deleted from a layout for example. 1618 Undoing a deletion does not cause a block to become valid again, you need to search for it again by time and track number. 1619 If the livesApp::mode() is changed from LIVES_INTERFACE_MODE_MULTITRACK, then all existing blocks become invalid. 1620 @return whether the block is contained in an active multitrack instance. 1621 */ 1622 bool isValid() const; 1623 1624 /** 1625 Returns a reference to the block on the specified track at the specified time. If no such block exists, returns an invalid block. 1626 @param m the multitrack object 1627 @param track the track number. Values < 0 indicate backing audio tracks. 1628 @param time the time in seconds on the timeline. 1629 @return the block on the given track at the given time. 1630 */ 1631 block(multitrack m, int track, double time); 1632 1633 /** 1634 Returns the start time in seconds of the block. 1635 If the block is invalid, returns -1. 1636 @return start time in seconds. 1637 */ 1638 double startTime(); 1639 1640 /** 1641 Returns the duration in seconds of the block. 1642 If the block is invalid, returns -1. 1643 @return duration in seconds. 1644 */ 1645 double length(); 1646 1647 /** 1648 Returns the clip which is the source of frames for this block. 1649 If the block is invalid, returns an invalid clip. 1650 @return the clip which is the source of frames for this block. 1651 */ 1652 clip clipSource(); 1653 1654 /** 1655 Returns the track number to which this block is currently attached. 1656 A track number < 0 indicates a backing audio track. 1657 If the block is invalid, returns 0. 1658 @return the current track number for this block. 1659 */ 1660 int track(); 1661 1662 /** 1663 Removes a block from the multitrack timeline. Upon being removed, the block becomes invalid. 1664 Undoing the operation does not cause the block to become valid again, although it can be searched for using the constructor. 1665 If the block is invalid, nothing happens and false is returned. 1666 Only works if livesApp::status() is LIVES_STATUS_READY. 1667 May cause other blocks to move, depending on the setting of multitrack::gravity(). 1668 @return true if the block was removed. 1669 @see multitrack::insertBlock(). 1670 */ 1671 bool remove(); 1672 1673 /** 1674 Move the block to a new track at a new timeline time. 1675 Depending on the value of multitrack::insertMode(), it may not be possible to do the insertion. 1676 In case of failure an invalid block is returned. 1677 Only works if livesApp::status() is LIVES_STATUS_READY and isActive() is true. 1678 Note: the actual place where the block ends up, and its final size depends on various factors such as the multitrack::gravity() setting, 1679 the multitrack::insertMode() setting, and the location of other blocks in the layout. 1680 The insertion may cause other blocks to relocate. 1681 If the block is invalid, nothing happens and false is returned. 1682 @param track the new track to move to. 1683 @param time the timeline time in seconds to move to. 1684 @return true if the block could be moved. 1685 */ 1686 bool moveTo(int track, double time); 1687 1688 1689 1690 protected: 1691 /** 1692 Protected initialiser 1693 */ 1694 block(multitrack *m = NULL, ulong uid = 0l); 1695 1696 1697 private: 1698 ulong m_uid; 1699 livesApp *m_lives; 1700 1701 void invalidate(); 1702 }; 1703 1704 1705 1706 /** 1707 class "multitrack". 1708 Represents the multitrack object in a livesApp. 1709 */ 1710 class multitrack { 1711 friend livesApp; 1712 friend block; 1713 1714 public: 1715 1716 /** 1717 returns whether the multitrack is valid or not. A valid multitrack is one which is owned by a valid livesApp, 1718 whose livesApp::status() is not LIVES_STATUS_NOTREADY. 1719 @return whether the multitrack is valid 1720 */ 1721 bool isValid() const; 1722 1723 /** 1724 returns whether the multitrack is active or not. This is equivent to livesApp::mode() == LIVES_INTERFACE_MODE_MULTITRACK. 1725 @return whether the multitrack is active or not. 1726 */ 1727 bool isActive() const; 1728 1729 /** 1730 Set the current track if isActive() is true. 1731 Only works when livesApp::status() is LIVES_STATUS_READY or LIVES_STATUS_PLAYING. 1732 @param track a value >= 0 represents a video track, a value < 0 represents a backing audio track. 1733 @return true if the track setting was successful. 1734 @see currentTrack(). 1735 */ 1736 bool setCurrentTrack(int track) const; 1737 1738 /** 1739 If isActive() is true, then this method returns the current active track. 1740 The active track defines the insertion point for video and audio, along with the currentTime(). 1741 If isActive() is false, or the livesApp::status is not LIVES_STATUS_READY or LIVES_STATUS_PLAYING 1742 then the return value is undefined. 1743 @return the current active track in multitrack mode. A value >= 0 represents a video track, a value < 0 represents a backing audio track. 1744 @see setCurrentTrack(). 1745 */ 1746 int currentTrack() const; 1747 1748 /** 1749 Set the current playback start time in seconds. This is also the insertion point for insertBlock(). 1750 Only works if the livesApp::status() is LIVES_STATUS_READY and isActive() is true. 1751 Setting the current time may cause the timeline to stretch visually (i.e zoom out). 1752 The miminum value is 0.0; values < 0.0 will be ignored. 1753 This function is synonymous with player::setPlaybackTime(). 1754 @param time the time in seconds to set playback start time to. 1755 @return the new playback start time. 1756 @see currentTime(). 1757 */ 1758 double setCurrentTime(double time) const; 1759 1760 /** 1761 Return the current playback time in seconds. If isActive() is true this returns the current player time in the multitrack timeline 1762 (equivalent to to player::playbackTime(), and during playback, equivalent to player::elapsedTime() plus a constant offset). 1763 This function works when livesApp::status() is LIVE_STATUS_READY or LIVES_STATUS_PLAYING. 1764 If isActive() is false, 0. is returned. 1765 @return the current clip playback time. 1766 @see setCurrentTime(). 1767 @see currentAudioTime(). 1768 @see elapsedTime(). 1769 */ 1770 double currentTime() const; 1771 1772 /** 1773 If isActive() is true, then this method returns the label for a track. 1774 @param track the track number. A value >= 0 represents a video track, a value < 0 represents a backing audio track. 1775 @return the track label, or empty livesString if the specified track does not exist. 1776 @see setTrackLabel(). 1777 */ 1778 livesString trackLabel(int track) const; 1779 1780 /** 1781 Set the label for a track. This is for display purposes only and has no other effect. 1782 If isActive() is false, the track label is not changed, and false is returned. 1783 If the label is not provided, or is an empty livesString, the user will be prompted to enter a name at runtime. 1784 @param track the track number. Must be >= 0. 1785 @param label a livesString containing the text to label the track with. 1786 @return true if it was possible to change the label. 1787 @see trackLabel(). 1788 */ 1789 bool setTrackLabel(int track, livesString label = livesString()) const; 1790 1791 /** 1792 Returns the value of the multitrack gravity. This value, together with the insertMode() defines what happens when a block is inserted, 1793 moved or deleted. 1794 If isActive() is false, the return value is undefined. 1795 @return the multitrack gravity. 1796 @see insertMode(). 1797 */ 1798 lives_gravity_t gravity() const; 1799 1800 /** 1801 Set the gravity mode for multitrack. If isActive() is false, nothing happens and an undefined value is returned, 1802 otherwise if livesApp::status() is not LIVES_STATUS_READY or LIVES_STATUS_PLAYING, nothing happens. 1803 @param mode the new gravity mode to set. 1804 @return the new gravity mode. 1805 @see gravity(). 1806 */ 1807 lives_gravity_t setGravity(lives_gravity_t mode) const; 1808 1809 /** 1810 Returns the value of the multitrack insert mode. This value, together with gravity() defines what happens when a block is inserted, 1811 moved or deleted. 1812 If isActive() is false, the return value is undefined. 1813 @return the multitrack insert mode. 1814 @see gravity(). 1815 */ 1816 lives_insert_mode_t insertMode() const; 1817 1818 /** 1819 Set the gravity mode for multitrack. If isActive() is false, nothing happens and an undefined value is returned, 1820 otherwise if livesApp::status() is not LIVES_STATUS_READY or LIVES_STATUS_PLAYING, nothing happens. 1821 @param mode the new insert mode to set. 1822 @return the new insert mode. 1823 @see insertMode(). 1824 */ 1825 lives_insert_mode_t setInsertMode(lives_insert_mode_t mode) const; 1826 1827 1828 /** 1829 Append a new video track into the timeline. Only works if isActive() is true, and livesApp::status() is LIVES_STATUS_READY. 1830 @param in_front set to true to insert a video track in front of existing video tracks. Otherwise insert will be behind. 1831 @return the index number of the newly added track, or -1 if the operation failed. 1832 */ 1833 int addVideoTrack(bool in_front) const; 1834 1835 1836 /** 1837 Returns the number of video tracks for multitrack. If isActive() is false, 0 is returned. 1838 @return the number of video tracks 1839 @see addVideoTrack() 1840 */ 1841 int numVideoTracks() const; 1842 1843 1844 /** 1845 Returns the number of audio backing tracks for multitrack. If isActive() is false, 0 is returned. 1846 @return the number of audio tracks 1847 */ 1848 int numAudioTracks() const; 1849 1850 1851 /** 1852 Return the framerate of the multitrack in frames per second. 1853 If isActive() is false, returns 0. Otherwise when the livesAPP::status() is LIVES_STATUS_PLAYING, player::FPS() takes this value. 1854 @return the framerate of the multitrack in frames per second. 1855 */ 1856 double FPS() const; 1857 1858 /** 1859 Insert frames from clip c into currentTrack() at currentTime() 1860 If ignore_selection_limits is true, then all frames from the clip will be inserted, 1861 otherwise (the default) only frames from clip::selectionStart() to clip::selectionEnd() will be used. 1862 If without_audio is false (the default), audio is also inserted. 1863 Frames are automatically resampled to fit layout::fps(). 1864 Depending on the insertMode(), it may not be possible to do the insertion. In case of failure an invalid block is returned. 1865 If the current track is a backing audio track, then only audio is inserted; 1866 in this case if without_audio is true an invalid block is returned. 1867 Only works if livesApp::status() is LIVES_STATUS_READY and isActive() is true. 1868 Note: the actual place where the block ends up, and its final size depends on various factors such as the gravity() setting, 1869 the insertMode() setting, and the location of other blocks in the layout. 1870 The insertion may cause other blocks to relocate. 1871 @param c the clip to insert from 1872 @param ignore_selection_limits if true then all frames from the clip will be inserted 1873 @param without_audio if false then audio is also inserted 1874 @return the newly inserted block. 1875 @see setCurrentTrack(). 1876 @see setCurrentTime(). 1877 @see clip::setSelectionStart(). 1878 @see clip::setSelectionEnd(). 1879 @see setGravity(). 1880 @see block::remove(). 1881 */ 1882 block insertBlock(clip c, bool ignore_selection_limits = false, bool without_audio = false) const; 1883 1884 /** 1885 Wipe the current layout, leaving a blank layout. 1886 If force is false, then the user will have a chance to cancel (if livesApp::interactive() is true), 1887 or to save the layout. 1888 Only works if livesApp::status() is LIVES_STATUS_READY and isActive() is true. 1889 Otherwise, the layout will not be wiped, and an empty livesString will be returned. 1890 @param force set to true to force the layout to be wiped. 1891 @return the name which the layout was saved to, or empty livesString if it was not saved. 1892 */ 1893 livesString wipeLayout(bool force = false) const; 1894 1895 /** 1896 Allow the user to graphically choose a layout to load for the set. 1897 Only works if livesApp::status() is LIVES_STATUS_READY and isActive() is true, otherwise an empty livesString is returned. 1898 @return the name of the layout selected. 1899 @see reloadLayout(). 1900 @see availableLayouts(). 1901 */ 1902 livesString chooseLayout() const; 1903 1904 /** 1905 Return a list of the available layouts for the currently loaded set. 1906 If livesApp::isReady() is false, or if no set is loaded, then an empty livesStringList is returned. 1907 @return list of available layouts for the currently loaded set 1908 @see reloadLayout(). 1909 */ 1910 livesStringList availableLayouts() const; 1911 1912 /** 1913 Reload the selected layout, replacing the current multitrack layout. 1914 Only works if livesApp::status() is LIVES_STATUS_READY and isActive() is true. 1915 The layout must be "owned" by the currently loaded set, otherwise an error may be shown and it will not be loaded. 1916 If filename is an empty livesString, chooseLayout() will be called first to get the layout name. 1917 If livesApp::interactive() is true, the user will have a chance to save the current layout (if any) first. 1918 @param filename the filename of the layout to load 1919 @return true if the specified layout could be loaded 1920 @see chooseLayout(). 1921 @see availableLayouts(). 1922 @see saveLayout(). 1923 */ 1924 bool reloadLayout(livesString filename) const; 1925 1926 /** 1927 Save the current layout using the name supplied. The layout will be saved in the layouts directory for the 1928 currently loaded set, so the name should not include any directory component. 1929 Only works if the livesApp::status() is LIVES_STATUS_READY, and the current layout is not empty, 1930 otherwise an empty livesString is returned. Note that this WILL work even if isActive() is false. 1931 If livesApp::interactive() is true, the user may choose to cancel the operation. 1932 If the layout name is empty, the user will be prompted graphically to enter a name. If the set name is empty, the user will be 1933 prompted to enter a set name (if livesApp::interactive() is true; otherwise this will fail and an empty string will be returned). 1934 Rarely it will not be possible to save a layout (if it was generated by recording events, and it contains generated audio or video). 1935 @param name the name to save the layout 1936 @return the filename the set was saved to, or empty livesString if saving failed. 1937 @see wipeLayout(). 1938 @see reloadLayout(); 1939 @see set::setName(). 1940 */ 1941 livesString saveLayout(livesString name) const; 1942 1943 /** 1944 Save the current layout using the current layout name. 1945 Only works if the livesApp::status() is LIVES_STATUS_READY, and the current layout is not empty, 1946 otherwise an empty livesString is returned. Note that this WILL work even if isActive() is false. 1947 If livesApp::interactive() is true, the user may choose to cancel the operation. 1948 If the layout name has not been previously set, the user will be prompted graphically to enter a name. 1949 If the set name is empty, the user will be 1950 prompted to enter a set name (if livesApp::interactive() is true; otherwise this will fail and an empty string will be returned). 1951 Rarely it will not be possible to save a layout (if it was generated by recording events, and it contains generated audio or video). 1952 @return the filename the set was saved to, or empty livesString if saving failed. 1953 @see wipeLayout(). 1954 @see reloadLayout(); 1955 @see set::setName(). 1956 */ 1957 livesString saveLayout() const; 1958 1959 /** 1960 Render the current layout to a new clip and return it. 1961 Only works if isActive() is true, and livesApp::status() is LIVES_STATUS_READY, and the current layout is not empty. 1962 If livesApp::interactive() is true, the user may choose to cancel the operation, or to render fewer than all frames. 1963 After rendering, if prefs::mtExitRender() is true, the livesApp::mode() will change to LIVES_INTERFACE_MODE_CLIPEDIT, 1964 and isActive() will change to false. 1965 @param render_audio true if audio should be rendered in addition to video. 1966 @param normalise_audio if true then the audio volume is normalized (backing audio gets half volume, video tracks get half volume) 1967 @return clip a new clip which contains the rendered video, or an invalid clip in case of failure. 1968 */ 1969 clip render(bool render_audio = true, bool normalise_audio = true) const; 1970 1971 /** 1972 Returns the current autotransition effect for multitrack mode. 1973 If no effect is set, returns an invalid effect. 1974 If the owning livesApp::isInvalid() is true, or if livesApp::Status() is LIVES_STATUS_NOTREADY, returns an invalid effect. 1975 @return the autotransition effect for multitrack. 1976 @see setAutoTransition(). 1977 @see disableAutoTransition(). 1978 */ 1979 effect autoTransition() const; 1980 1981 /** 1982 Set the current autotransition effect for multitrack mode to "None" (no effect). 1983 If the livesApp::status() is not LIVES_STATUS_READY or LIVES_STATUS_PLAYING, returns false and nothing happens. 1984 @return true if the autotransition was disabled. 1985 @see autoTransition(). 1986 @see setAutoTransition(). 1987 */ 1988 bool disableAutoTransition() const; 1989 1990 /** 1991 Set the current autotransition effect for multitrack mode. 1992 If the livesApp::status() is not LIVES_STATUS_READY or LIVES_STATUS_PLAYING, returns false and nothing happens. 1993 If the effect is not a transition, false is returned and nothing happens. 1994 If the effect is invalid, this is the same as calling disableAutoTransition(). 1995 @param autotrans the new autotransition effect for multitrack. 1996 @return true if the autotransition was changed. 1997 @see autoTransition(). 1998 @see disableAutoTransition(). 1999 */ 2000 bool setAutoTransition(effect autotrans) const; 2001 2002 /** 2003 @return true if the two layouts have the same livesApp owner 2004 */ operator ==(const multitrack & other) const2005 inline bool operator==(const multitrack &other) const { 2006 return m_lives == other.m_lives; 2007 } 2008 2009 2010 protected: 2011 multitrack(livesApp *lives = NULL); 2012 2013 /** 2014 The linked LiVES application 2015 */ 2016 livesApp *m_lives; 2017 2018 2019 }; 2020 2021 2022 2023 2024 2025 2026 /** 2027 Preferences. Valid values are only returned if the livesApp::isValid() is true, and livesApp::status() is not LIVES_STATUS_NOTREADY. 2028 Implementation note: we use const livesApp & here to avoid the destructor being called on a copy object, 2029 which would cause LiVES to terminate prematurely. 2030 */ 2031 namespace prefs { 2032 /** 2033 @param lives a reference to a valid livesApp instance 2034 @return the currently preferred directory for loading video clips. 2035 */ 2036 livesString currentVideoLoadDir(const livesApp &lives); 2037 2038 /** 2039 @param lives a reference to a valid const livesApp &instance 2040 @return the currently preferred directory for loading and saving audio. 2041 */ 2042 livesString currentAudioDir(const livesApp &lives); 2043 2044 /** 2045 Despite the name, this is the working directory for the LiVES application. 2046 The valid list of sets is drawn from this directory, for it is here that they are saved and loaded. 2047 The value can only be set at runtime through the GUI preferences window. Otherwise you can override the default value 2048 when the livesApp() is created via argv[] option "-tmpdir", eg: <BR> 2049 <BR><BLOCKQUOTE><I> 2050 char *argv[2]; <BR> 2051 argv[0]="-tmpdir"; <BR> 2052 argv[1]="/home/user/tempdir/"; <BR> 2053 livesApp lives(2, argv); <BR> 2054 </I></BLOCKQUOTE> 2055 @param lives a reference to a valid livesApp instance 2056 @return the LiVES working directory 2057 */ 2058 livesString tmpDir(const livesApp &lives); 2059 2060 /** 2061 @param lives a reference to a valid livesApp instance 2062 @return the current audio source 2063 @see setAudioSource(). 2064 */ 2065 lives_audio_source_t audioSource(const livesApp &lives); 2066 2067 /** 2068 Set the audio source. Only works if livesApp::status() is LIVES_STATUS_READY. 2069 @param lives a reference to a valid livesApp instance 2070 @param asrc the desired audio source 2071 @return true if the audio source could be changed. 2072 */ 2073 bool setAudioSource(const livesApp &lives, lives_audio_source_t asrc); 2074 2075 /** 2076 @param lives a reference to a livesApp instance 2077 @return the current audio player 2078 */ 2079 lives_audio_player_t audioPlayer(const livesApp &lives); 2080 2081 /** 2082 Returns the audio rate for the player. Note this may be different from the clip audio rate. 2083 Only valid if isRealtimeAudioPlayer(lives.audioPlayer()) is true. 2084 @param lives a reference to a livesApp instance 2085 @return the current audio player rate in Hz. 2086 @see isRealtimeAudioPlayer() 2087 */ 2088 int audioPlayerRate(const livesApp &lives); 2089 2090 /** 2091 @param ptype an audio player type 2092 @return true if the audio player type is realtime controllable 2093 */ 2094 bool isRealtimeAudioPlayer(lives_audio_player_t ptype); 2095 2096 /** 2097 @param lives a reference to a valid livesApp instance 2098 @return the maximum value for effectKey indices 2099 */ 2100 int rteKeysVirtual(const livesApp &lives); 2101 2102 /** 2103 @param lives a reference to a valid livesApp instance 2104 @return the maximum allowed framerate for a clip 2105 */ 2106 double maxFPS(const livesApp &lives); 2107 2108 /** 2109 @param lives a reference to a valid livesApp instance 2110 @return true if the audio clip changes to match video clip changes during playback 2111 @see setAudioFollowsVideoChanges(). 2112 */ 2113 bool audioFollowsVideoChanges(const livesApp &lives); 2114 2115 /** 2116 @param lives a reference to a valid livesApp instance 2117 @return true if the clip audio playback rate changes to match video clip framerate changes during playback 2118 @see setAudioFollowsFPSChanges(). 2119 */ 2120 bool audioFollowsFPSChanges(const livesApp &lives); 2121 2122 /** 2123 @param lives a reference to a valid livesApp instance 2124 @param setting the new setting 2125 @return true if the preference was updated 2126 @see audioFollowsFPSChanges 2127 */ 2128 bool setAudioFollowsFPSChanges(const livesApp &lives, bool setting); 2129 2130 /** 2131 @param lives a reference to a valid livesApp instance 2132 @param setting the new setting 2133 @return true if the preference was updated 2134 @see audioFollowsFPSChanges 2135 */ 2136 bool setAudioFollowsVideoChanges(const livesApp &lives, bool setting); 2137 2138 /** 2139 @param lives a reference to a valid livesApp instance 2140 @return true if the separate playback window is shown even when livesApp::isPlaying() is false. 2141 @see setSepWinSticky() 2142 @see player::sepWin() 2143 */ 2144 bool sepWinSticky(const livesApp &lives); 2145 2146 /** 2147 @param lives a reference to a valid livesApp instance 2148 @return true if the preference was updated 2149 @see sepWinSticky() 2150 @see player::sepWin() 2151 */ 2152 bool setSepWinSticky(const livesApp &lives, bool); 2153 2154 /** 2155 @param lives a reference to a valid livesApp instance 2156 @return true if the livesApp::mode() switches to LIVES_INTERFACE_MODE_CLIPEDIT after calling multitrack::render() 2157 @see setMtExitRender() 2158 @see multitrack::render() 2159 */ 2160 bool mtExitRender(const livesApp &lives); 2161 2162 /** 2163 @param lives a reference to a valid livesApp instance 2164 @param setting the new setting 2165 @return true if the preference was updated 2166 @see mtExitRender(). 2167 @see multitrack::render(). 2168 */ 2169 bool setMtExitRender(const livesApp &lives, bool setting); 2170 2171 2172 } 2173 2174 2175 } 2176 2177 #endif // __cplusplus 2178 2179 #endif //HAS_LIBLIVES_H 2180