1/* 2 This file is part of the KDE project 3 Copyright (C) 2005-2007 Matthias Kretz <kretz@kde.org> 4 Copyright (C) 2015 The Qt Company Ltd. 5 Contact: http://www.qt.io/licensing/ 6 7 This library is free software; you can redistribute it and/or 8 modify it under the terms of the GNU Library General Public 9 License version 2 as published by the Free Software Foundation. 10 11 This library is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Library General Public License for more details. 15 16 You should have received a copy of the GNU Library General Public License 17 along with this library; see the file COPYING.LIB. If not, write to 18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 19 Boston, MA 02110-1301, USA. 20*/ 21 22 23/*! 24 \enum Phonon::DiscType 25 Enum to identify the media discs supported by MediaObject. 26 27 \value NoDisc 28 No disc was selected. This is only useful as a return value from 29 MediaSource::diskType(). 30 \value Cd Identifies Audio CDs. 31 \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs). 32 \value Vcd Identifies Video CDs. 33 34 \sa MediaSource, MediaObject 35*/ 36 37/*! 38 \enum Phonon::MetaData 39 40 Provided as keys for Phonon::MediaObject::metaData(). The enum 41 values matches strings defined in the Ogg Vorbis specification 42 43 \value ArtistMetaData 44 \value AlbumMetaData 45 \value TitleMetaData 46 \value DateMetaData 47 \value GenreMetaData 48 \value TracknumberMetaData 49 \value DescriptionMetaData 50 \value MusicBrainzDiscIdMetaData 51*/ 52 53/*! 54 \enum Phonon::State 55 \since 4.4 56 57 The state enum describes the different states a media object can 58 take. Several functions of \l{Phonon::}{MediaObject} are 59 asynchronous, so even if a you have requested a state change 60 through a function call, e.g., through 61 \l{Phonon::MediaObject::}{play()}, you cannot be sure that the 62 change has taken place before you receive the 63 \l{Phonon::MediaObject::}{stateChanged()} signal. 64 65 A media object can at any time change into any state, regardless 66 of the state it previously had. \omit In the 67 \l{Phonon::}{MediaObject} class description explains the typical 68 state changes in the life of a media object. \endomit 69 70 \value LoadingState 71 After construction it might take a while before the media object 72 is ready to \l{Phonon::MediaObject::}{play()}. This state is 73 commonly used by backends to initialize the \l{Phonon 74 Overview}{media graph} and loading the source. When 75 the object leaves the loading state, it will enter the 76 StoppedState unless an error occurred or another state is 77 requested through a function call, e.g., 78 \l{Phonon::}{MediaObject::play()}. 79 80 \value StoppedState 81 In the stopped state, the media object is ready to play its 82 current media source. The current 83 \l{MediaObject::seek()}{position} in the media stream is then 0. 84 85 \value PlayingState 86 The media object is playing back its media source. 87 88 \value BufferingState 89 The Player is waiting for data to be able to start or continue 90 playing. This state is commonly used to wait for media data over a 91 network connection. 92 93 \value PausedState 94 The media player has currently paused its playback, i.e., it 95 stops playing but keeps the current playback position in the 96 stream. 97 98 \value ErrorState 99 When a media object enters the error state a problem with the 100 playback has occurred. The possible errors are grouped into 101 two categories by Phonon::ErrorType, and the type can be 102 queried through \l{Phonon::MediaObject::}{errorType()}. A 103 \l{Phonon::}{FatalError} implies that the playback 104 cannot continue, but one can still try with a new media 105 source. With a \l{Phonon::}{NormalError} it might 106 be possible to continue playback, and a media object may 107 therefore change state from the ErrorState. 108 109 \sa MediaObject 110*/ 111 112/*! 113 \enum Phonon::Category 114 115 Sets the category your program should be listed in in the mixer. 116 117 \value NoCategory 118 Will make use of the default device. 119 \value NotificationCategory 120 If the sounds produced are notifications (ping, beep and such) you 121 should use this category. 122 \value MusicCategory 123 If your application is a music player (like a jukebox or media player 124 playing an audio file). 125 \value VideoCategory 126 If the sound is the audio channel of a video. 127 \value CommunicationCategory 128 If your applications produces sounds from communication with somebody 129 else (VoIP, voice chat). 130 \value GameCategory 131 Sound produced by a computer game should go into this category. 132 \value AccessibilityCategory 133 Sounds produced for accessibility (e.g., Text-To-Speech) 134 \omitvalue LastCategory 135 Holds the largest value of categories. 136 \omitvalue AccessibilityCategory 137 138 A Jukebox will set this to Music, a VoIP program to Communication, a 139 DVD player to video, and so on. 140 141 \note These categories can also become useful for an application that 142 controls the volumes automatically, like turning down the music when a call 143 comes in, or turning down the notifications when the media player knows 144 it's playing classical music. 145*/ 146 147/*! 148 \enum Phonon::ErrorType 149 150 This enum describes the severity when an error has occurred during 151 playback. 152 153 After a media object has entered the \l{Phonon::}{ErrorState}, one 154 can query the type of error from 155 \l{Phonon::}{MediaObject::errorType()}. Note that you should query 156 the error when receiving the 157 \l{Phonon::}{MediaObject::stateChanged()} signal, because the 158 error type will be lost if the media object leaves the error 159 state. 160 161 \value NoError No error. MediaObject::errorType() returns this if 162 MediaObject::state() != Phonon::ErrorState. 163 164 \value NormalError An error has occurred with the playback of the current 165 source. It might be possible to continue playback, for instance, if only the 166 audio stream in a video cannot be played back. The media object will then 167 leave the error state again. 168 169 \value FatalError. Something important does not work. Your program cannot continue 170 the playback of the current source, but it might be possible to try another. 171 172 \sa MediaObject::errorType() 173*/ 174 175/*! 176 \fn QString Phonon::categoryToString(Category c) 177 178 Returns a (translated) string to show to the user identifying the given 179 Category (\a c). 180*/ 181 182/*! 183 \enum Phonon::ObjectDescriptionType 184 \relates Phonon::ObjectDescription 185 186 This enum defines the type of information that is contained in a 187 \l{Phonon::}{ObjectDescription} object. 188 189 \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}). 190 This can be soundcards (with different drivers), 191 sound servers, or other virtual outputs like playback on a different 192 computer on the network. 193 194 \value EffectType An audio effect (\l{Phonon::}{EffectDescription}). 195 \omitvalue SubtitleType 196 \omitvalue AudioCaptureDeviceType 197 \omitvalue AudioChannelType 198*/ 199 200/*! 201 \typedef Phonon::AudioOutputDevice 202 \relates Phonon::ObjectDescription 203 204 This typedef of \l{Phonon::}{ObjectDescription} describes an audio output 205 device, such as soundcards (with different drivers), sound servers, or other 206 virtual outputs like playback on a different computer on the network. 207 208 \omit 209 For Hardware devices the backend should use libkaudiodevicelist 210 (AudioDevice and AudioDeviceEnumerator) which will list removable 211 devices even when they are unplugged and provide a unique identifier 212 that can make backends use the same identifiers. 213 \endomit 214 215 A list of available devices is given by the backend with 216 Backendcapabilities::availableAudioOutputDevices() 217 218 \snippet doc/src/snippets/phononobjectdescription.cpp 1 219 220*/ 221 222/*! 223 \fn Phonon::phononVersion() 224 \inmodule Phonon 225 \since 4.5 226 227 Returns the Phonon version. 228*/ 229 230/*! 231 \class Phonon::ObjectDescription 232 \inmodule Phonon 233 \inheaderfile Phonon/ObjectDescription 234 \since 4.4 235 \brief The ObjectDescription class provides information about Phonon objects. 236 237 Phonon currently uses this class to describe audio effects and 238 audio output devices - using the typedefs AudioOutputDevice and 239 EffectDescription. The type of an ObjectDescription is also 240 described through the \l{Phonon::}{ObjectDescriptionType} enum. 241 Objects of the same \l{Phonon::ObjectDescriptionType}{type} are 242 uniquely identified by an index(). 243 244 The class gives a description() and a name() of the object, both 245 of which are strings appropriate for end users of a Phonon 246 application. You can also check whether the device or effect 247 described is \l{isValid()}{valid}. This does not guarantee that 248 the device or effect functions as expected, but that the 249 ObjectDescription describes an existing device or effect. 250 251 Audio output devices and effect descriptions are used to select 252 the audio output device to be used for playback and to create 253 effects; we show examples of this in the snippet below. The 254 available descriptions can be fetched with 255 \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} 256 and \l{Phonon::BackendCapabilities::}{availableAudioEffects()} 257 static functions in the Phonon::BackendCapabilities namespace 258 259 \snippet doc/src/snippets/phononobjectdescription.cpp 0 260 261 Other types of ObjectDescriptions might be possible in the future, 262 e.g., descriptions of audio capture devices, such as microphones. 263 264 \omit Not implemented yet. 265 Need a new paragraph on that some descriptions 'belong 266 together', such as chained audio effects. 267 268 Some parts give the end user choices, e.g. what source to capture 269 audio from. These choices are described by the name and 270 description methods of this class and identified with the id 271 method. Subclasses then define additional information like which 272 audio and video choices belong together. \endomit 273 274 \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module} 275*/ 276 277/*! 278 \fn Phonon::ObjectDescription::ObjectDescription() 279 \brief constructs a new object description. 280 \internal 281*/ 282 283/*! 284 \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash<QByteArray, QVariant> & properties) 285 \internal 286*/ 287 288/*! 289 \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd) 290 \internal 291*/ 292 293/*! 294 \fn static inline ObjectDescription<T> Phonon::ObjectDescription::fromIndex(int index) 295 \internal 296 297 \omit Currently indices are not unique for all ObjectDescription types, making 298 the behavior of this function undefined. \endomit 299 300 Returns a new description object that describes the 301 device/effect/codec/... with the given \a index. 302*/ 303 304/*! 305 \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const 306 307 Returns \c true if this ObjectDescription describes the same 308 object as \a otherDescription; otherwise, returns \c false. 309*/ 310 311/*! 312 \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const 313 Returns \c false if this ObjectDescription describes the same 314 as \a otherDescription; otherwise, returns \c true. 315*/ 316 317/*! 318 \fn inline QString Phonon::ObjectDescription::name() const 319 320 Returns a string appropriate for a user to select between 321 object descriptions, e.g., from a QComboBox. 322 323 \sa description() 324*/ 325 326/*! 327 \fn inline QString Phonon::ObjectDescription::description() const 328 329 Returns a more extensive description than the name() function. 330 331 For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this 332 text should make clear which sound source is described; this is 333 sometimes hard to describe or understand from just the name. 334 335 The text is appropriate to present to an end user in for example 336 tool tips of items, with the name()'s as text, in a QComboBox. 337 338*/ 339 340/*! 341 \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const 342 343 Returns the property named \a name. A property can be used for 344 extended information, such as the manufacturer of a sound card. The 345 information will usually be given as text. 346 347 If the property is not set an invalid QVariant is returned. 348 349 Qt's backends do not use properties at the time of this writing. 350 351 \sa propertyNames() 352*/ 353 354/*! 355 \fn inline QList<QByteArray> Phonon::ObjectDescription::propertyNames() const 356 357 Properties can be used for extended information about a 358 ObjectDescription, e.g., a manufacturer of a sound card. The 359 information will usually be given text. 360 361 This function returns all names that return valid data when 362 property() is called. 363 364 Currently, Qt backends do not use properties for their object 365 descriptions. 366 367 \sa property() 368*/ 369 370/*! 371 \fn inline bool Phonon::ObjectDescription::isValid() const 372 373 Returns true if the device or effect described exists. 374 375 An ObjectDescription that is invalid, will also have an 376 index() of -1. 377 378 \sa index() 379*/ 380 381/*! 382 \fn inline int Phonon::ObjectDescription::index() const 383 384 Returns a unique identifier for this ObjectDescription. Used 385 internally to distinguish between the descriptions. 386 387 Notice that the identifiers are only unique to the type of 388 description, e.g., \l{Phonon::}{AudioOutputDevice} or 389 \l{Phonon::}{EffectDescription}. 390*/ 391 392/*! 393 \class Phonon::ObjectDescriptionPrivate 394 \inmodule Phonon 395 \since 4.4 396 \internal 397 398*/ 399 400/*! 401 \class Phonon::StreamInterface 402 \inmodule Phonon 403 \since 4.4 404 \brief Backend interface to handle media streams (AbstractMediaStream). 405 \internal 406*/ 407 408/*! 409 \fn virtual Phonon::StreamInterface::~StreamInterface() 410*/ 411 412/*! 413 \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0 414 \internal 415*/ 416 417/*! 418 \fn virtual void Phonon::StreamInterface::endOfData() = 0 419 \internal 420*/ 421 422/*! 423 \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0 424 \internal 425*/ 426 427/*! 428 \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0 429 \internal 430*/ 431 432/*! 433 \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource) 434 \internal 435*/ 436 437/*! 438 \fn void Phonon::StreamInterface::needData() 439 \internal 440*/ 441 442/*! 443 \fn void Phonon::StreamInterface::enoughData() 444 \internal 445*/ 446 447/*! 448 \fn void Phonon::StreamInterface::seekStream(qint64) 449 \internal 450*/ 451 452/*! 453 \fn void Phonon::StreamInterface::reset() 454 \internal 455*/ 456 457/*! 458 \fn Phonon::StreamInterface::StreamInterface() 459 \internal 460 \omit 461 For subclasses. 462 \endomit 463*/ 464 465/*! 466 \class StreamInterfacePrivate 467 \inmodule Phonon 468 \internal 469*/ 470 471/*! 472 \class Phonon::AbstractVideoOutput 473 \inmodule Phonon 474 \internal 475 \since 4.4 476 \brief The AbstractVideoOutput class is the common base class for all video output classes. 477 478 \sa VideoWidget 479*/ 480 481/*! 482 \namespace Phonon::Experimental 483 \internal 484*/ 485 486/*! 487 \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d) 488 \internal 489 490 Constructor that is called from derived classes. 491 492 \param parent Standard QObject parent. 493*/ 494 495/*! 496 \class Phonon::AbstractVideoOutputPrivate 497 \inmodule Phonon 498 \internal 499 \since 4.4 500*/ 501 502/*! 503 \class Phonon::VolumeFaderEffect 504 \inmodule Phonon 505 \internal 506 \since 4.4 507 508 This effect differs from gradually changing the output volume in that 509 a dedicated effect can change the volume in the smallest possible 510 steps while every other volume control will make more or less 511 noticeable steps. 512 513 \sa AudioOutput::volume() 514*/ 515 516/*! 517 \property Phonon::VolumeFaderEffect::volume 518 519 This is the current volume of the output as voltage factor. 520 Setting this property changes the volume immediately. 521 522 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% 523 524 \sa volumeDecibel 525*/ 526 527/*! 528 \property Phonon::VolumeFaderEffect::volumeDecibel 529 530 This is the current volume of the output in decibel. 531 Setting this property changes the volume immediately. 532 533 0 dB means no change in volume, -6dB means an attenuation of the 534 voltage to 50% and an attenuation of the power to 25%, -inf dB means 535 silence. 536 537 \sa volume 538*/ 539 540/*! 541 \property Phonon::VolumeFaderEffect::fadeCurve 542 543 This property holds the fade curve to be used for the fadeIn(), fadeOut() 544 and fadeTo() slots. 545 546 Defaults to Fade3Decibel. 547 548 \sa FadeCurve 549*/ 550 551/*! 552 \enum Phonon::VolumeFaderEffect::FadeCurve 553 Determines the curve of the volume change. 554 555 \value Fade3Decibel Crossfade curve/fast fade out. 556 This is the default fade curve. 557 \value Fade6Decibel Linear fade out. 558 \value Fade9Decibel Slow fade out. 559 \value Fade12Decibel A more extreme version of the -9dB fade. 560 561 \bold{Notes:} 562 563 \c Fade3Decibel is often the best fade for a crossfade, as after half 564 of the time the volume reached -3dB. This means that half the 565 possible power (which is proportional to the square of the 566 voltage) is reached. Summed, the maximum power of two audio 567 signals fading with a -3dB curve will always be equal. 568 569 For fading in or out the -3dB curve is too abrupt in the end. 570 571 With a -6dB fade curve, a volume of -6dB is reached after half of 572 the fading time. -6dB is equal to half of the voltage meaning 573 that the voltage multiplier changes linearly from the start 574 of the fade to the end. 575 576 With the \c Fade9Decibel fade, a volume of -9dB is reached after 577 half of the fade time, so the fade is fast in the beginning and 578 slow at the end. This is a good fade for ending music. 579*/ 580 581/*! 582 \fn void Phonon::VolumeFaderEffect::fadeIn(int fadeTime) 583 584 Tells the Fader to change the volume from the current volume to 100% 585 in \a fadeTime milliseconds. 586 587 Short for \c fadeTo(1.0, fadeTime). 588 589 \param fadeTime the fade duration in milliseconds 590 591 \sa fadeTo(), volume 592*/ 593 594/*! 595 \fn void Phonon::VolumeFaderEffect::fadeOut(int fadeTime) 596 597 Tells the Fader to change the volume from the current volume to 0% 598 in \a fadeTime milliseconds. 599 Short for \c fadeTo(0.0, fadeTime). 600 601 \param fadeTime the fade duration in milliseconds 602 603 \sa fadeTo 604*/ 605 606/*! 607 \fn void Phonon::VolumeFaderEffect::fadeTo(float volume, int fadeTime) 608 609 Tells the Fader to change the volume from the current value to 610 \a volume in \a fadeTime milliseconds. 611 612 \sa fadeIn(), fadeOut() 613*/ 614 615/*! 616 \class Phonon::VolumeFaderEffectPrivate 617 \inmodule Phonon 618 \since 4.4 619 \internal 620*/ 621 622/*! 623 \class Phonon::VolumeFaderInterface 624 \inmodule Phonon 625 \since 4.4 626 \internal 627*/ 628 629/*! 630 \fn virtual Phonon::VolumeFaderInterface::~VolumeFaderInterface() 631 \internal 632*/ 633 634/*! 635 \fn virtual float Phonon::VolumeFaderInterface::volume() const 636 \internal 637*/ 638 639/*! 640 \fn virtual void Phonon::VolumeFaderInterface::setVolume(float) 641 \internal 642*/ 643 644/*! 645 \fn virtual Phonon::VolumeFaderEffect::FadeCurve Phonon::VolumeFaderInterface::fadeCurve() const 646 \internal 647*/ 648 649/*! 650 \fn virtual void Phonon::VolumeFaderInterface::setFadeCurve(Phonon::VolumeFaderEffect::FadeCurve) 651 \internal 652*/ 653 654/*! 655 \fn virtual void Phonon::VolumeFaderInterface::fadeTo(float, int) 656 \internal 657*/ 658 659/*! 660 \class Phonon::AbstractMediaStream 661 \inmodule Phonon 662 \internal 663 \since 4.4 664 \brief The AbstractMediaStream class is the base class for custom media data streams. 665 \inheaderfile Phonon/AbstractMediaStream 666 667 This class is subclassed to provide custom data streams for 668 \l{Phonon::}{MediaSource}s. 669 670 The \l{Phonon::}{MediaSource} knows how to handle the most common 671 media sources, such as files and CD. If you need to fetch 672 multimedia from other sources, you can reimplement this class, 673 which can be used by a \l{Phonon::}{MediaSource}. 674 675 When a backend needs more data from the stream, needData() will be 676 called. You must then use writeData() to write the data to the 677 backend. You can either write one time and wait for a new 678 needData() call, or continue to write data until you receive an 679 enoughData() call. When the stream is at its end, call endOfData() 680 instead of writeData(). 681 682 Before the custom stream is passed to a \l{Phonon::}{MediaSource}, 683 setStreamSize() needs to be called, and also setStreamSeekable() 684 (if the stream is seekable). A good place to do this work is in 685 the constructor. A seekable stream must also reimplement 686 seekStream(). 687 688 We show two examples. The first writes data repeatedly until it 689 receives the enoughData() call, while the second only writes once 690 and waits for a new needData() call. 691 692 Example where data is written repeatedly. 693 694 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 0 695 696 Example where data is written once: 697 698 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 1 699 700 \sa Phonon::MediaSource, Phonon::MediaObject 701 702*/ 703 704/*! 705 \fn Phonon::AbstractMediaStream::AbstractMediaStream(QObject *parent = 0) 706 \internal 707 708 Constructs an AbstractMediaStream object with the given \a parent. 709 710*/ 711 712/*! 713 \fn qint64 Phonon::AbstractMediaStream::streamSize() const 714 715 Returns the stream size that was set with setStreamSize(). 716 717 A negative value means that the length of the stream cannot be known. 718 719 Defaults to 0. 720 721 \sa setStreamSize() 722*/ 723 724/*! 725 \fn void Phonon::AbstractMediaStream::setStreamSize(qint64 size) 726 727 Sets the \a size of the stream in number of bytes. 728 729 A negative value means that the length of the stream cannot be known. 730 731 Defaults to 0. 732 733 This function has to be called. A backend will not call needData() 734 until the stream size is set. 735 736 \sa streamSize() 737 738*/ 739 740/*! 741 \fn bool Phonon::AbstractMediaStream::streamSeekable() const 742 743 Returns whether your data stream is set as seekable. 744 745 Defaults to \c false. 746 747 \sa setStreamSeekable() 748 749*/ 750 751/*! 752 \fn void Phonon::AbstractMediaStream::setStreamSeekable(bool s) 753 754 Sets whether your data stream is seekable. \a s should be true if 755 the stream is seekable; otherwise false. 756 757 Defaults to \c false. 758 759 If you set this to \c true you have to implement the seekStream() 760 function. 761 762 \sa streamSeekable() 763*/ 764 765/*! 766 \fn void Phonon::AbstractMediaStream::writeData(const QByteArray &data) 767 768 Sends the media \a data to the backend for decoding. 769 770 Use this function to send data to the backend after needData() has 771 been called. 772 773 If your stream is a push stream, data should be written until the 774 enoughData() function is called. For a pull stream, write data 775 once before the call to needData() function returns. 776 777 If the data is depleted, call endOfData() instead of writeData(). 778 779 \warning Don't call this function before the first needData() is emitted. 780 781 \sa needData(), endOfData() 782 783*/ 784 785/*! 786 \fn void Phonon::AbstractMediaStream::endOfData() 787 788 Tells the backend that the media data stream is at its end. 789 790 \warning Don't call this function before the first needData() is emitted. 791 792 \sa writeData(), needData() 793*/ 794 795/*! 796 \fn void Phonon::AbstractMediaStream::error(Phonon::ErrorType errorType, const QString &errorString) 797 798 If an I/O error occurs you should call this function to make 799 MediaObject go into ErrorState. \c errorType classifies the error, 800 while \a errorString is a textual description of the error suitable 801 for users of Phonon applications. 802 803 \sa MediaObject::errorType(), MediaObject::errorString() 804*/ 805 806/*! 807 \fn virtual void Phonon::AbstractMediaStream::reset() = 0 808 809 Reimplement this function to reset the stream. Subsequent calls to writeData should start 810 from the first position of the data unless a seek is requested. 811 812 The function is necessary for the case where a non-seekable MediaStream is 813 played more than once. For a seekable stream the implementation can simply call 814 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 2 815 816 \sa writeData(), needData() 817*/ 818 819/*! 820 \fn virtual void Phonon::AbstractMediaStream::needData() = 0 821 822 Reimplement this function to be notified when the backend needs data. 823 824 When this function is called you should write data to the backend 825 (See writeData()). 826 827 \sa writeData(), endOfData(), enoughData() 828*/ 829 830/*! 831 \fn virtual void Phonon::AbstractMediaStream::enoughData() 832 833 If your stream is a push stream, reimplement this function to be 834 notified when the backend has enough data and your stream object 835 may take a break. 836 837 This method is important for pushing data to the backend in order 838 to not fill the backend buffer unnecessarily. 839 840 \sa needData() 841*/ 842 843/*! 844 \fn virtual void Phonon::AbstractMediaStream::seekStream(qint64 offset) 845 846 Reimplement this function if your stream is seekable. 847 848 When this function is called the next call to writeData has to be at the 849 requested \a offset. 850 851 \warning Do not call the parent implementation. 852 853 \sa setStreamSeekable(), streamSeekable(), needData() 854*/ 855 856/*! 857 \class Phonon::BackendInterface 858 \inmodule Phonon 859 \since 4.4 860 \brief Main Backend class interface 861 \internal 862 863 This interface defines the main factory of the backend. The createObject() function creates all the 864 objects needed by the frontend. 865 866 The objectDescriptionIndexes and objectDescriptionProperties functions return information about 867 available devices, effects and codecs. 868 869 An implementation could look like this: 870 \snippet snippets/phonon/samplebackend/main.cpp snippet 871 872*/ 873 874/*! 875 \fn virtual Phonon::BackendInterface::~BackendInterface() 876 \internal 877 878 Silence gcc's warning. 879*/ 880 881/*! 882 \enum Phonon::BackendInterface::Class 883 \internal 884 885 Classes that the createObject() function has to handle. 886 887 \value MediaObjectClass Request to return a \c MediaObject object. 888 \value VolumeFaderEffectClass Request to return a \c VolumeFaderEffect 889 object. 890 \value AudioOutputClass Request to return an \c AudioOutput object. 891 \value AudioDataOutputClass Request to return an \c AudioDataOutput object. 892 \value VisualizationClass Request to return a \c Visualization object. 893 \value VideoDataOutputClass Request to return a \c VideoDataOutput object. 894 \value EffectClass Request to return a \c Effect object. 895 Takes an additional int that specifies the effect ID. 896 \value VideoWidgetClass Request to return a \c VideoWidget object. 897*/ 898 899/*! 900 \fn virtual QObject *Phonon::BackendInterface::createObject(Class c, QObject *parent, const QList<QVariant> &args = QList<QVariant>()) = 0 901 \internal 902 903 Returns a new instance of the requested class. 904 905 \param c The requested class. 906 \param parent The parent object. 907 \param args Additional arguments (documented in Class). 908*/ 909 910 911/*! 912 \fn virtual QList<int> Phonon::BackendInterface::objectDescriptionIndexes(ObjectDescriptionType type) const = 0 913 \internal 914 915 Returns the unique identifiers for the devices/effects/codecs of the given \a type. 916 917 \param type see ObjectDescriptionType 918*/ 919 920/*! 921 \fn virtual QHash<QByteArray, QVariant> Phonon::BackendInterface::objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0 922 \internal 923 924 Given a unique identifier that was returned from objectDescriptionIndexes this function 925 returns a hash mapping property names to values. 926 927 The property "name" must always be present. All other properties are optional. 928 929 \table 930 \header \o Property \o Description 931 \row \o name \o The name of the device/effect/codec/... 932 \row \o description \o A text explaining what this device/effect/codec/... is/can do 933 \row \o icon \o An icon name (using the freedesktop naming scheme) or a QIcon for this 934 device/effect/codec/... 935 \row \o available \o A bool telling whether the device is present or unplugged. 936 \endtable 937 938 \param type see ObjectDescriptionType 939 \param index The unique identifier that is returned from objectDescriptionIndexes 940*/ 941 942/*! 943 \fn virtual bool Phonon::BackendInterface::startConnectionChange(QSet<QObject *>) = 0; 944 \internal 945 946 When this function is called the nodes given in the parameter list should 947 not lose any signal data when connections are changed. 948*/ 949 950/*! 951 \fn virtual bool Phonon::BackendInterface::connectNodes(QObject *, QObject *) = 0 952 \internal 953 954 Defines a signal connection between the two given nodes. 955*/ 956 957/*! 958 \fn virtual bool Phonon::BackendInterface::disconnectNodes(QObject *, QObject *) = 0 959 \internal 960 961 Cuts a signal connection between the two given nodes. 962*/ 963 964/*! 965 \fn virtual bool Phonon::BackendInterface::endConnectionChange(QSet<QObject *>) = 0 966 \internal 967 968 When this function is called the nodes given in the parameter list may lose 969 signal data when a port is not connected. 970*/ 971 972/*! 973 \fn virtual QStringList Phonon::BackendInterface::availableMimeTypes() const = 0 974 \internal 975 976 Returns all available MIME types. 977*/ 978 979/*! 980 \class Phonon::MediaSource 981 \inmodule Phonon 982 \inheaderfile Phonon/MediaSource 983 \since 4.4 984 \brief The MediaSource class provides multimedia data for media objects. 985 986 The MediaSource class manages a source of multimedia content, such 987 as a music or video file, of which data is given to a 988 \l{Phonon::}{MediaObject}. 989 990 The media source knows how fetch its data from several sources, 991 e.g., from files, a QIODevice, or a CD. The possible source types 992 are described by the \l{MediaSource::}{Type} enum. The type of the 993 source is set by the media source itself, and is dependent on the 994 constructor used to create it. Note that it is possible to provide 995 data from any source by implementing a QIODevice. 996 997 The class has several functions to acquire information about the 998 source it manages, e.g., fileName() and url(). The return from 999 these functions are dependent on the type() of the media source. 1000 1001 Normally, a programmer does not need to be concerned with media 1002 sources. It's constructors are implicit, so one can, for instance, 1003 send an URL or filename directly to the constructors of the 1004 \l{Phonon::}{MediaObject}. 1005 1006 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 3 1007 1008 A MediaSource object cannot be reused for another multimedia 1009 source. It is possible to play the same source again, and also 1010 stop and start a non-seekable media source, such as a radio 1011 stream, with the same MediaSource object. 1012 1013 \section1 Qt Backends 1014 1015 Currently, Qt's backends support files in local and remote 1016 locations. Support for other sources, such as CD/DVD, are planned 1017 for the future. 1018 1019 \sa MediaObject, {Phonon Module} 1020*/ 1021 1022/*! 1023 \enum Phonon::MediaSource::Type 1024 1025 Identifies the type of media described by the MediaSource object. 1026 1027 \value Invalid The MediaSource object does not describe any valid source. 1028 \value LocalFile The MediaSource object describes a local file. 1029 \value Url The MediaSource object describes an URL, which can be either a 1030 local file or a file on the network. 1031 \value Disc The MediaSource object describes a disc, e.g., a CD. 1032 \value Stream The MediaSource object describes a data stream. 1033 This is the type used for \l{QIODevice}s. Note 1034 that a stream opened with a QUrl, will still be of the Url type. 1035 \value Empty The media source doesn't have a source. 1036 1037 \sa MediaSource::type() 1038*/ 1039 1040/*! 1041 \fn Phonon::MediaSource::MediaSource() 1042 \internal 1043 1044 Creates an invalid MediaSource object. 1045 1046 \sa Invalid 1047*/ 1048 1049/*! 1050 \fn Phonon::MediaSource::MediaSource(const QString &fileName) 1051 1052 Creates a MediaSource object for the file specified by \a 1053 fileName. You can also use this constructor with \l{The Qt 1054 Resource System}{Qt resources} 1055 1056 \omit 1057 \param fileName file name of a local media file or a Qt resource that was compiled in. 1058 \endomit 1059*/ 1060 1061/*! 1062 \fn Phonon::MediaSource::MediaSource(const QUrl &url) 1063 1064 Creates a MediaSource object for a the URL specified by \a url. 1065 1066 If the multimedia content you would like to play back is on a 1067 remote network location, you should use this constructor; though, 1068 it also possible to specify an URL to a local file. 1069 1070 \sa QUrl 1071*/ 1072 1073 1074/*! 1075 \fn Phonon::MediaSource::MediaSource(Phonon::DiscType discType, const QString &deviceName = QString()) 1076 1077 Creates a MediaSource object for the type of disc specified by \a discType in the named 1078 device referred to by \a deviceName. 1079 1080 \note \a deviceName is a platform dependent device name. It can be useful to specify this 1081 if the computer has more than one CD drive. On KDE, it is recommended to use the Solid 1082 hardware discovery framework to retrieve the device name in a portable way. 1083*/ 1084 1085/*! 1086 \fn Phonon::MediaSource::MediaSource(AbstractMediaStream *stream) 1087 \internal 1088 Creates a MediaSource object for a data stream. 1089 1090 Your application can provide the media data by subclassing AbstractMediaStream and 1091 passing a pointer to that object. Phonon will never delete the \a stream. 1092 1093 \param stream The AbstractMediaStream subclass to provide the media data. 1094 1095 \sa setAutoDelete 1096*/ 1097 1098/*! 1099 \fn Phonon::MediaSource::MediaSource(QIODevice *ioDevice) 1100 1101 Creates a MediaSource object for the QIODevice specified by \a ioDevice. 1102 1103 This constructor can be very handy in the combination of 1104 QByteArray and QBuffer. 1105 1106 If you need to fetch multimedia data from a source that is not 1107 supported by MediaSource, you should subclass QIODevice and use 1108 this MediaSource constructor. It is important that you reimplement 1109 QIODevice::isSequential(), as it is used by MediaSource to 1110 determine if the media source is seekable. 1111 1112 \a ioDevice is an arbitrary readable QIODevice subclass. If the device is not opened 1113 MediaSource will open it as QIODevice::ReadOnly. 1114 1115 \note Sequential devices can also be used, but MediaObject::isSeekable() will 1116 return false as a result. 1117 1118 \warning On Windows, we only support \l{QIODevice}s containing the 1119 \c avi, \c mp3, or \c mpg formats. Use the constructor that takes 1120 a file name to open files (the Qt backend does not use a QFile 1121 internally). 1122 1123 \sa setAutoDelete() 1124*/ 1125 1126/*! 1127 \fn Phonon::MediaSource::MediaSource(MediaSourcePrivate &) 1128 \internal 1129*/ 1130 1131/*! 1132 \fn Phonon::MediaSource::~MediaSource() 1133 1134 Destroys the MediaSource object. You should never delete a 1135 MediaSource yourself, the MediaObject will handle this. 1136 1137*/ 1138 1139/*! 1140 \fn Phonon::MediaSource::MediaSource(const MediaSource &other) 1141 1142 Constructs a copy of the \a other media source. 1143 1144 This constructor is fast thanks to explicit sharing. 1145*/ 1146 1147/*! 1148 \fn MediaSource &Phonon::MediaSource::operator=(const MediaSource &other) 1149 1150 Assigns the \a other media source to this media source and returns a 1151 reference to it. 1152 1153 This operation is fast thanks to explicit sharing. 1154*/ 1155 1156/*! 1157 \fn bool Phonon::MediaSource::operator==(const MediaSource &other) const 1158 1159 Returns true if this media source is equal to the \a other media source; 1160 otherwise returns false. 1161*/ 1162 1163/*! 1164 \fn void Phonon::MediaSource::setAutoDelete(bool enable) 1165 1166 If \a enable is true, the media source will take ownership of the 1167 object passed in the \l{Phonon::}{MediaSource}'s constructor 1168 object that was passed in the constructor; otherwise, the 1169 programmer is responsible for deletion of this object. 1170 1171 This setting is false by default. If you enable it, you should 1172 only access the stream or device as long as you keep the media 1173 source object around. As long as you keep the media source 1174 wrapping the stream or device, the object will not get deleted. 1175 1176 \sa autoDelete() 1177*/ 1178 1179/*! 1180 \fn bool Phonon::MediaSource::autoDelete() const 1181 1182 Returns the setting of the auto-delete option. The default is 1183 false. 1184 1185 \sa setAutoDelete() 1186*/ 1187 1188/*! 1189 \fn Type Phonon::MediaSource::type() const 1190 1191 Returns the type of the MediaSource (depends on the constructor 1192 that was used). 1193 1194 \sa Type 1195*/ 1196 1197/*! 1198 \fn QString Phonon::MediaSource::fileName() const 1199 1200 Returns the file name of the MediaSource if type() == 1201 LocalFile; otherwise, returns QString(). 1202 1203 \sa type() 1204*/ 1205 1206/*! 1207 \fn QUrl Phonon::MediaSource::url() const 1208 Returns the URL of the MediaSource if type() == URL or type() == LocalFile; 1209 otherwise returns QUrl(). 1210 1211 \sa type() 1212*/ 1213 1214/*! 1215 \fn Phonon::DiscType Phonon::MediaSource::discType() const 1216 Returns the disc type of the MediaSource if type() == Disc; otherwise 1217 returns NoDisc. 1218 1219 \sa type() 1220*/ 1221 1222/*! 1223 \fn QString Phonon::MediaSource::deviceName() const 1224 1225 Returns the device name of the MediaSource if type() == Disc; otherwise 1226 returns QString(). 1227 1228 \sa type() 1229*/ 1230 1231/*! 1232 \fn AbstractMediaStream *Phonon::MediaSource::stream() const 1233 \internal 1234 Returns the media stream of the MediaSource if type() == Stream; otherwise 1235 returns 0. 1236 QIODevices are handled as streams, too. 1237*/ 1238 1239/*! 1240 \class Phonon::MediaSourcePrivate 1241 \inmodule Phonon 1242 \since 4.4 1243 \internal 1244*/ 1245 1246/*! 1247 \class Phonon::SeekSlider 1248 \inmodule Phonon 1249 \inheaderfile Phonon/SeekSlider 1250 \since 4.4 1251 \brief The SeekSlider class provides a slider for seeking to positions in media streams. 1252 1253 The SeekSlider connects to a \l{Phonon::}{MediaObject}, and 1254 controls the seek position in the object's media stream. 1255 1256 The slider will connect to the necessary signals to keep track of 1257 the sliders maximum, minimum, and current values. It will also 1258 disable itself for non-seekable streams, and update the media 1259 object when the current value of the slider changes. 1260 1261 Here follows a typical example of SeekSlider usage: 1262 1263 \snippet doc/src/snippets/seekslider.cpp 0 1264 1265 \sa Phonon::VolumeSlider, Phonon::VideoWidget, {Music Player Example}, {Phonon Module} 1266 1267*/ 1268 1269/*! 1270 \property Phonon::SeekSlider::iconVisible 1271 \brief whether the icon next to the slider is visible 1272 1273 By default the icon is visible if the platform provides an icon; else 1274 it's hidden. 1275 1276*/ 1277 1278/*! 1279 \property Phonon::SeekSlider::tracking 1280 \brief whether slider tracking is enabled 1281 1282 If tracking is enabled (the default), the media seeks 1283 while the slider is being dragged. If tracking is 1284 disabled, the media seeks only when the user 1285 releases the slider. 1286*/ 1287 1288/*! 1289 \property Phonon::SeekSlider::pageStep 1290 \brief the page step interval 1291 1292 The larger of two natural steps that a slider provides and 1293 typically corresponds to the user pressing PageUp or PageDown. 1294 1295 Defaults to 5 seconds. 1296*/ 1297 1298/*! 1299 \property Phonon::SeekSlider::singleStep 1300 \brief the single step interval 1301 1302 The smaller of two natural steps that a slider provides and 1303 typically corresponds to the user pressing an arrow key. 1304 1305 Defaults to 0.5 seconds. 1306*/ 1307 1308/*! 1309 \property Phonon::SeekSlider::orientation 1310 \brief the orientation of the slider 1311 1312 The orientation must be Qt::Vertical or Qt::Horizontal (the default). 1313*/ 1314 1315/*! 1316 \property Phonon::SeekSlider::iconSize 1317 \brief the icon size used for the mute button/icon. 1318 1319 The default size is defined by the GUI style. 1320*/ 1321 1322/*! 1323 \fn explicit Phonon::SeekSlider::SeekSlider(QWidget *parent = 0) 1324 1325 Constructs a seek slider widget with the given \a parent. 1326*/ 1327 1328/*! 1329 \fn explicit Phonon::SeekSlider::SeekSlider(MediaObject *media, QWidget *parent = 0) 1330 1331 Constructs a seek slider widget for the specified \a media with the 1332 given \a parent. 1333*/ 1334 1335/*! 1336 \fn Phonon::SeekSlider::~SeekSlider() 1337 Destroys the seek slider. 1338*/ 1339 1340/*! 1341 \fn Phonon::MediaObject *Phonon::SeekSlider::mediaObject() const 1342 1343 Return the media object this SeekSlider controls. 1344*/ 1345 1346/*! 1347 \class Phonon::SeekSliderPrivate 1348 \inmodule Phonon 1349 \since 4.4 1350 \internal 1351*/ 1352 1353/*! 1354 \fn void Phonon::SeekSlider::setMediaObject(MediaObject *media) 1355 1356 Sets the media object to be controlled by this slider to the \a media specified. 1357*/ 1358 1359/*! 1360 \class Phonon::VideoPlayer 1361 \inmodule Phonon 1362 \inheaderfile Phonon/VideoPlayer 1363 \since 4.4 1364 \brief The VideoPlayer widget is used to perform playback of video. 1365 1366 With VideoPlayer you can get results quickly and easily. You can 1367 do the standard playback tasks like play(), pause(), and stop(), 1368 but also set a playback volume and seek - if the media and backend 1369 supports seeking. 1370 1371 VideoPlayer is provided for convenience and removes the need to 1372 create a media graph with a \l{Phonon::}{MediaObject}, 1373 \l{Phonon::}{AudioOutput}, and \l{Phonon::}{VideoWidget}. If 1374 you need functionality not supported by the player, you can build 1375 this \l{Building Graphs}{graph} yourself. 1376 1377 Keep in mind that when the VideoPlayer instance is deleted the 1378 playback will stop. 1379 1380 Note also that most of the functions in this class are 1381 asynchronous. For instance, a media source may not play 1382 immediately after you call the play() function. 1383 1384 A play and forget code example: 1385 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 4 1386 1387 \sa {Phonon Module}, MediaObject 1388*/ 1389 1390/*! 1391 \fn Phonon::VideoPlayer::VideoPlayer(QWidget *parent = 0) 1392 1393 Constructs a new video widget with a \a parent using 1394 Phonon::VideoCategory as its category. 1395 1396 \param parent The QObject parent. 1397*/ 1398 1399/*! 1400 \fn Phonon::VideoPlayer::VideoPlayer(Phonon::Category category, QWidget *parent = 0) 1401 1402 Constructs a new VideoPlayer instance with the specified \a 1403 parent. 1404 1405 \a category is the category used for the audio output device. 1406*/ 1407 1408/*! 1409 \fn Phonon::VideoPlayer::~VideoPlayer() 1410 1411 On destruction the playback is stopped, also the audio output is 1412 removed so that the desktop mixer will not show the application 1413 anymore. If you need a persistent audio output don't use 1414 VideoPlayer but MediaObject, VideoPath and VideoOutput. 1415*/ 1416 1417/*! 1418 \fn qint64 Phonon::VideoPlayer::totalTime() const 1419 1420 Get the total time (in milliseconds) of the file currently being played. 1421*/ 1422 1423/*! 1424 \fn qint64 Phonon::VideoPlayer::currentTime() const 1425 1426 Get the current time (in milliseconds) of the file currently being played. 1427*/ 1428 1429/*! 1430 \fn float Phonon::VideoPlayer::volume() const 1431 1432 This is the current volume of the output as voltage factor. 1433 1434 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% 1435*/ 1436 1437/*! 1438 \fn bool Phonon::VideoPlayer::isPlaying() const 1439 1440 Returns true if it is currently playing; otherwise returns false if it 1441 is currently stopped or paused 1442*/ 1443 1444/*! 1445 \fn bool Phonon::VideoPlayer::isPaused() const 1446 1447 Returns true if it is currently paused; otherwise returns false if it 1448 is currently playing or stopped. 1449*/ 1450 1451/*! 1452 \fn void Phonon::VideoPlayer::load(const Phonon::MediaSource &source) 1453 1454 Starts pre-loading the media data from the specified \a source and 1455 filling audio buffers in the backend. 1456 1457 When there's already a media playing (or paused) it will be stopped 1458 (the finished signal will not be emitted). 1459 1460 \sa MediaObject::setCurrentSource() 1461*/ 1462 1463/*! 1464 \fn void Phonon::VideoPlayer::play(const Phonon::MediaSource &source) 1465 1466 Plays the media from the given \a source. Starts playback as fast as 1467 possible. 1468 This can take a considerable time depending on the URL and the 1469 backend. 1470 1471 If you need low latency between calling play() and the sound actually 1472 starting to play on your output device you need to use MediaObject 1473 and be able to set the URL before calling play(). Note that 1474 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 5 1475 doesn't make a difference: the application should be idle between the 1476 load and play calls so that the backend can start preloading the 1477 media and fill audio buffers. 1478*/ 1479 1480/*! 1481 \fn void Phonon::VideoPlayer::play() 1482 1483 Continues playback of paused media. Restarts playback of a stopped 1484 (or newly loaded) media. 1485 1486 \sa MediaObject::play(), play() 1487*/ 1488 1489/*! 1490 \fn void Phonon::VideoPlayer::pause() 1491 1492 Pauses the playback. 1493 1494 \sa MediaObject::pause() 1495*/ 1496 1497/*! 1498 \fn void Phonon::VideoPlayer::stop() 1499 1500 Stops the playback. 1501 1502 \sa MediaObject::stop() 1503*/ 1504 1505/*! 1506 \fn void Phonon::VideoPlayer::seek(qint64 ms) 1507 1508 Seeks to the requested time. Note that the backend is free to 1509 ignore the seek request if the media source isn't seekable; you 1510 can check this by asking the media object of the VideoPlayer. 1511 1512 \snippet doc/src/snippets/videomedia.cpp 0 1513 1514 The \a ms parameter is the time in milliseconds from the start of 1515 the media. 1516 1517 The call is asynchronous, so currentTime() can still be the old 1518 value right after this method was called. If all you need is a 1519 slider that shows the current position and allows the user to 1520 seek, use the class SeekSlider. 1521 1522 \sa MediaObject::seek(), MediaObject::isSeekable(), mediaObject() 1523*/ 1524 1525/*! 1526 \fn void Phonon::VideoPlayer::setVolume(float volume) 1527 1528 Sets the \a volume of the output as voltage factor. 1529 1530 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% 1531*/ 1532 1533/*! 1534 \fn MediaObject *Phonon::VideoPlayer::mediaObject() const 1535 1536 Returns the media object being used by the player. 1537 1538 The media object can be accessed directly instead of using the 1539 \l{VideoPlayer}s convenience functions, e.g., play() and stop(). 1540 It is also possible to give the object to other Phonon widgets, 1541 e.g., a \l{Phonon::}{SeekSlider} or a \l{Phonon::}{VolumeSlider}. 1542 1543 \sa Phonon::SeekSlider, Phonon::MediaObject 1544*/ 1545 1546/*! 1547 \fn AudioOutput *Phonon::VideoPlayer::audioOutput() const 1548 1549 Returns the audio output object being used by the player. 1550 1551*/ 1552 1553/*! 1554 \fn VideoWidget *Phonon::VideoPlayer::videoWidget() const 1555 1556 Returns the video widget being used by the player. 1557*/ 1558 1559/*! 1560 \fn void Phonon::VideoPlayer::finished() 1561 1562 This signal is emitted when the playback finished. 1563 1564*/ 1565 1566/*! 1567 \class Phonon::VideoWidgetPrivate 1568 \inmodule Phonon 1569 \since 4.4 1570 \internal 1571*/ 1572 1573/*! 1574 \class Phonon::MediaObject 1575 \inmodule Phonon 1576 \inheaderfile Phonon/MediaObject 1577 \since 4.4 1578 \brief The MediaObject class provides an interface for media playback. 1579 1580 The media object manages a \l{Phonon::}{MediaSource}, which 1581 supplies the media object with multimedia content, e.g., from a 1582 file. A playback in Phonon is always started by calling the 1583 \l{Phonon::MediaObject::}{play()} function. 1584 1585 The state of play (play, pause, stop, seek) is controlled by the 1586 media object, and you can also query the current 1587 \l{Phonon::MediaObject::}{state()}. It keeps track of the playback 1588 position in the media stream, and emits the 1589 \l{Phonon::MediaObject::}{tick()} signal when the current position 1590 in the stream changes. 1591 1592 Notice that most functions of this class are asynchronous, so you 1593 cannot rely on that a state is entered after a function call 1594 before you receive the \l{Phonon::MediaObject::}{stateChanged()} 1595 signal. The description of the \l{Phonon::}{State} enum gives a 1596 description of the different states. 1597 1598 Before play() is called, the media object should be connected to 1599 \l{Sinks}{output nodes}, which outputs the media to the 1600 underlying hardware. The output nodes required are dependent on 1601 the contents of the multimedia file that is played back. Phonon 1602 has currently two output nodes: the \l{Phonon::}{AudioOutput} for 1603 audio content and \l{Phonon::}{VideoWidget} for video content. If 1604 a \l{Phonon::}{MediaSource} contains both audio and video, both 1605 nodes need to be connected to the media object. 1606 1607 \snippet snippets/phonon.cpp 4 1608 \snippet snippets/phonon.cpp 5 1609 1610 The media object can queue sources for playback. When it has 1611 finished to play one source, it will start playing the next in the 1612 queue; the new source is then removed from the queue. The 1613 queue can be altered at any time. 1614 1615 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 7 1616 1617 You can also make use of the 1618 \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is 1619 guaranteed to be emitted in time for altering the queue. 1620 1621 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 8 1622 1623 When playback is finishing, i.e., when a media source has been 1624 played to the end and the queue is empty, several signals are 1625 emitted. First, the media object will emit aboutToFinish() - 1626 shortly before the playback has finished - and then finished(). 1627 The stateChanged() signal will also be emitted with 1628 \l{Phonon::}{PausedState}, which is the state the media object 1629 takes when the playback is finished. If you wish to enter another 1630 state, you can connect a slot to finished() and set a new state 1631 there. 1632 1633 The media object resolves the meta information, such as title, 1634 artist, and album. The meta data is not resolved immediately after 1635 a new source is provided, but will be resolved before the object 1636 leaves the \l{Phonon::}{LoadingState}. The data is queried by 1637 string keys - which should follow the Ogg Vorbis specification 1638 \l http://xiph.org/vorbis/doc/v-comment.html - or by using the 1639 \l{Phonon::}{MetaData} enum. The data available will depend on the 1640 type and content of the individual media files. metaDataChanged() 1641 will be emitted when the media object has resolved new meta data. 1642 1643 Errors encountered during playback and loading of media sources 1644 are reported by emitting a state changed signal with 1645 \l{Phonon::}{ErrorState}. The severity of the error can be queried 1646 by the \l{Phonon::}{ErrorType}. With a \l{Phonon::}{NormalError}, 1647 it might be possible to continue the playback, for instance, if 1648 only audio playback fails for a media source which also has video. 1649 A \l{Phonon::}{FatalError} indicates that Phonon cannot continue 1650 playback of the current source, but it is possible to try with a 1651 different one. A user readable error message is given by 1652 errorString(). 1653 1654 \sa {Symbian Platform Security Requirements} 1655 \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget, 1656 {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer, 1657 Phonon::createPlayer(), {Phonon Module} 1658 1659*/ 1660 1661/*! 1662 \property Phonon::MediaObject::transitionTime 1663 \brief Defines the time between playback of two media sources 1664 in the media queue. 1665 1666 A positive transition time defines a gap of silence between queued 1667 media sources. 1668 1669 A transition time of 0 ms requests gapless playback (i.e., the 1670 next source in the media queue starts immediately after the 1671 playback of the current source finishes). 1672 1673 A negative transition time defines a crossfade between the queued 1674 media sources. 1675 1676 Defaults to 0 (gapless playback). 1677 1678 \warning This feature might not work reliably with every 1679 backend. 1680*/ 1681 1682/*! 1683 \property Phonon::MediaObject::prefinishMark 1684 \brief the time when the prefinishMarkReached signal is emitted before playback ends. 1685 1686 This property specifies the time in milliseconds the 1687 prefinishMarkReached() signal is emitted before the playback 1688 finishes. A value of \c 0 disables the signal. The signal is only 1689 emitted for the last source in the \l{queue()}{media queue}. 1690 1691 Defaults to \c 0 (disabled). 1692 1693 \warning For some media data the total time cannot be determined 1694 accurately, therefore the accuracy of the prefinishMarkReached signal 1695 can be bad sometimes. Still, it is better to use this method than to 1696 look at totalTime() and currentTime() to emulate the behavior 1697 because the backend might have more information available than your 1698 application does through totalTime() and currentTime(). 1699 1700 \sa prefinishMarkReached() 1701*/ 1702 1703/*! 1704 \property Phonon::MediaObject::tickInterval 1705 \brief The time interval in milliseconds between two ticks. 1706 1707 The tick() signal is emitted continuously during playback. 1708 The tick interval is the time that elapses between the emission of two tick signals. 1709 If you set the interval to \c 0 the tick signal gets disabled. 1710 1711 The tick() signal can, for instance, be used to update widgets 1712 that show the current position in the playback of a media source. 1713 1714 Defaults to \c 0 (disabled). 1715 1716 \warning The back-end is free to choose a different tick interval close 1717 to what you asked for. This means that the following code \c may fail: 1718 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 9 1719 On the other hand the following is guaranteed: 1720 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 10 1721 1722 \sa tick() 1723*/ 1724 1725/*! 1726 \fn Phonon::MediaObject::~MediaObject() 1727 1728 Destroys the MediaObject. 1729*/ 1730 1731/*! 1732 \fn State Phonon::MediaObject::state() const 1733 1734 Returns the current Phonon::State of the object. 1735 1736 \sa Phonon::State, stateChanged() 1737*/ 1738 1739/*! 1740 \fn bool Phonon::MediaObject::hasVideo() const 1741 1742 Check whether the current media source includes a video stream. 1743 1744 \warning This information is not resolved immediately after a 1745 media object gets a new source. Listen to the hasVideoChanged() 1746 signal instead. 1747 1748 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 11 1749 1750 Returns \c true if the media contains video data; otherwise, 1751 returns \c false. 1752 1753 \sa hasVideoChanged() 1754*/ 1755 1756/*! 1757 \fn bool Phonon::MediaObject::isSeekable() const 1758 1759 Check whether it is possible to seek, i.e., change the 1760 playback position in the media stream. 1761 1762 \warning This information is not solved immediately after the 1763 media object gets a new media source. The hasVideoChanged() signal 1764 is emitted after this information is available. 1765 1766 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 12 1767 1768 Returns \c true if the current media may be seeked; otherwise, 1769 returns \c false. 1770 1771 \sa seekableChanged() 1772*/ 1773 1774/*! 1775 \fn QStringList Phonon::MediaObject::metaData(const QString &key) const 1776 1777 Returns the strings associated with the given \a key. 1778 1779 Backends should use the keys specified in the Ogg Vorbis 1780 documentation: \l http://xiph.org/vorbis/doc/v-comment.html 1781 1782 Therefore the following should work with every backend: 1783 1784 Note that meta data is not resolved before the \c 1785 metaDataChanged() signal is emitted. 1786 1787 A typical usage looks like this: 1788 1789 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 13 1790*/ 1791 1792/*! 1793 \fn QStringList Phonon::MediaObject::metaData(Phonon::MetaData key) const 1794 1795 Returns the strings associated with the given \a key. 1796 1797 Same as above except that the keys are defined in the 1798 Phonon::MetaData enum. 1799 1800 \sa metaDataChanged() 1801*/ 1802 1803/*! 1804 \fn QMultiMap<QString, QString> Phonon::MediaObject::metaData() const 1805 1806 Returns all meta data in a multi map. 1807 1808 \sa metaDataChanged() 1809*/ 1810 1811/*! 1812 \fn QString Phonon::MediaObject::errorString() const 1813 1814 Returns a human-readable description of the last error that occurred. 1815 The strings given may vary between backends. 1816 1817 The error description can be used to give a message to the user - 1818 and the developer - when the stateChanged() signal is emitted with 1819 \l{Phonon::}{ErrorState}. 1820 1821 \section1 Qt Backends 1822 1823 On Windows, Qt fetches its error messages from the DirectShow 1824 backend. This usually includes an error number, which can be 1825 looked up in the DirectShow documentation: 1826 \l{http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dx81_c/directx_cpp/htm/errorandsuccesscodes.asp}. 1827 1828 On Linux and Mac, the error strings are not fetched directly from 1829 the backend, but are created in the backend. 1830 1831 \sa Phonon::ErrorState, stateChanged() 1832*/ 1833 1834/*! 1835 \fn ErrorType Phonon::MediaObject::errorType() const 1836 1837 Tells your program what to do about the last error that occurred. 1838 Use this function after receiving a stateChanged() signal with 1839 \l{Phonon::}{ErrorState}. 1840 1841 \sa Phonon::ErrorType, Phonon::ErrorState, stateChanged() 1842*/ 1843 1844/*! 1845 \fn MediaSource Phonon::MediaObject::currentSource() const 1846 1847 Returns the current media source, i.e., the media source that is 1848 being played back. The current source is either set with 1849 setCurrentSource() or taken from the media queue() when a media 1850 source has finished playing. 1851 1852 \sa setCurrentSource() 1853*/ 1854 1855/*! 1856 \fn void Phonon::MediaObject::setCurrentSource(const MediaSource &source) 1857 1858 Set the media source the MediaObject should use. 1859 1860 After the media object receives a new source, it will enter the 1861 \l{Phonon::}{LoadingState}. When it is ready to play, it 1862 enters the \l{Phonon::}{StoppedState} unless another state 1863 has been requested, e.g., by calling play(). 1864 1865 \a source is the MediaSource object to the media data. You can 1866 just as well use a QUrl or QString (for a local file) here. 1867 1868 We show an example: 1869 1870 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 14 1871 1872 \sa currentSource(), MediaSource 1873*/ 1874 1875/*! 1876 \fn QList<MediaSource> Phonon::MediaObject::queue() const 1877 1878 Returns the queued media sources. 1879 1880 This does list does not include the current source, 1881 returned by currentSource(). 1882 1883 \sa enqueue() 1884*/ 1885 1886/*! 1887 \fn void Phonon::MediaObject::setQueue(const QList<MediaSource> &sources) 1888 1889 Set the \a sources to play when the current source has finished. 1890 1891 This function will overwrite the current queue. 1892 1893 \sa clearQueue(), enqueue() 1894*/ 1895 1896/*! 1897 \fn void Phonon::MediaObject::setQueue(const QList<QUrl> &urls) 1898 1899 Set the \a urls to play when the current media has finished. 1900 1901 This function overwrites the current queue. 1902 1903 \sa clearQueue(), enqueue() 1904*/ 1905 1906/*! 1907 \fn void Phonon::MediaObject::enqueue(const MediaSource &source) 1908 1909 Appends \a source to the queue. 1910 1911 You can use this function to provide the next source after the 1912 aboutToFinish() signal has been emitted. 1913 1914 \sa aboutToFinish(), setQueue(), clearQueue() 1915*/ 1916 1917/*! 1918 \fn void Phonon::MediaObject::enqueue(const QList<MediaSource> &sources) 1919 1920 Appends multiple \a sources to the queue. 1921 1922 \sa setQueue(), clearQueue() 1923*/ 1924 1925/*! 1926 \fn void Phonon::MediaObject::enqueue(const QList<QUrl> &urls) 1927 1928 Appends the URLs in \a urls to the media source queue. 1929 1930 The function will create \l{MediaSource}s from the \l{QUrl}s, and 1931 append these to the queue. 1932 1933 \sa setQueue(), clearQueue() 1934*/ 1935 1936/*! 1937 \fn void Phonon::MediaObject::clearQueue() 1938 1939 Clears the queue of media sources. 1940 1941 \sa queue(), enqueue() 1942*/ 1943 1944/*! 1945 \fn qint64 Phonon::MediaObject::currentTime() const 1946 1947 Returns the current time (in milliseconds), i.e., position in the 1948 media stream, of the file currently being played. 1949 1950 \sa tick(), totalTime(), remainingTime() 1951*/ 1952 1953/*! 1954 \fn qint64 Phonon::MediaObject::totalTime() const 1955 1956 Get the total time (in milliseconds) of the file currently being played. 1957 1958 Returns the total time in milliseconds. 1959 1960 \warning The total time is not defined before the media object 1961 enters the \l{Phonon::}{LoadingState}. 1962 1963 \sa totalTimeChanged() 1964*/ 1965 1966/*! 1967 \fn qint64 Phonon::MediaObject::remainingTime() const 1968 1969 Get the remaining time (in milliseconds) of the file currently being played. 1970 1971 Returns the remaining time in milliseconds. 1972 1973 \sa totalTime(), currentTime(), totalTimeChanged() 1974*/ 1975 1976/*! 1977 \fn void Phonon::MediaObject::play() 1978 1979 Requests playback of the media data to start. 1980 1981 Playback starts when the stateChanged() signal is emitted with 1982 \l{Phonon::}{PlayingState}. 1983 1984 If the media object is already in a 1985 \l{Phonon::}{PlayingState}, nothing happens. 1986 1987 \sa stop(), pause(), stateChanged() 1988*/ 1989 1990/*! 1991 \fn void Phonon::MediaObject::pause() 1992 1993 Requests playback to pause, and the media object to enter the 1994 \l{Phonon::}{PausedState}. If it was paused already, nothing 1995 changes. 1996 1997 This function is asynchronous and the media might not be paused 1998 immediately. 1999 2000 \sa play(), stop(), stateChanged() 2001*/ 2002 2003/*! 2004 \fn void Phonon::MediaObject::stop() 2005 2006 Requests playback to stop, and the media object to enter the 2007 \l{Phonon::}{StoppedState}. If it was stopped before 2008 nothing changes. 2009 2010 This function is asynchronous and the media might not be 2011 stopped immediately. 2012 2013 \sa play(), pause(), stateChanged() 2014*/ 2015 2016/*! 2017 \fn void Phonon::MediaObject::seek(qint64 time) 2018 2019 Requests a seek to the \a time indicated, specified in milliseconds. 2020 2021 You can only seek if state() is PlayingState, BufferingState or PausedState. 2022 2023 The call is asynchronous, so currentTime can still be the old 2024 value right after this method was called. If all you need is a 2025 slider that shows the current position and allows the user to 2026 seek, use the class SeekSlider. 2027 2028 If the current source of the media object is not seekable, calls 2029 to this functions do nothing. 2030 2031 \sa SeekSlider, tick() 2032*/ 2033 2034/*! 2035 \fn void Phonon::MediaObject::clear() 2036 2037 Stops and removes all playing and enqueued media sources. 2038 2039 \sa setCurrentSource() 2040*/ 2041 2042 2043/*! 2044 \fn void Phonon::MediaObject::stateChanged(Phonon::State newstate, Phonon::State oldstate) 2045 2046 This signal is emitted when the state of the MediaObject has changed. 2047 The \a oldstate and \a newstate parameters indicate the previous 2048 state and current state of the media object. 2049 2050 If you are only interested in the new state of the media object, you can 2051 connect this signal to a slot that accepts only one State argument. 2052*/ 2053 2054/*! 2055 \fn void Phonon::MediaObject::tick(qint64 time) 2056 2057 This signal is emitted in intervals defined by the 2058 \l{tickInterval} property. The current position of the media 2059 object in the stream is given by the \a time parameter. The \a 2060 time is specified in milliseconds. 2061 2062 \sa tickInterval 2063*/ 2064 2065/*! 2066 \fn void Phonon::MediaObject::metaDataChanged() 2067 2068 This signal is emitted when the media object has resolved new meta 2069 data. This will happen before the media object leaves the 2070 \l{Phonon::}{LoadingState} after a new source has been set. 2071 2072 This signal is not emitted when the media object removes the 2073 current data, i.e., when a new source is set or an error has 2074 occurred. If you need to know this, you can listen for the 2075 \l{Phonon::}{ErrorState}, and connect to the 2076 \l{Phonon::MediaObject::}{currentSourceChanged()} signal. 2077 2078 You can get the new meta data with the metaData methods. 2079 2080 \sa metaData(), currentSourceChanged(), stateChanged(), Phonon::State 2081*/ 2082 2083/*! 2084 \fn void Phonon::MediaObject::seekableChanged(bool isSeekable) 2085 2086 This signal is emitted when the media object's ability to seek in 2087 the media stream changes. \a isSeekable is true if it is possible 2088 to seek(); otherwise, it is false. 2089 2090 Change in the ability to seek in the stream usually happens when 2091 the current source changes or when an error occurs. 2092 2093 \omit Emitted whenever the return value of isSeekable() 2094 changes. \endomit 2095 2096 Normally you'll check isSeekable() after setting a new media 2097 source, and then let this signal tell you when seeking is 2098 possible. That way you don't have to poll isSeekable(). 2099*/ 2100 2101/*! 2102 \fn void Phonon::MediaObject::hasVideoChanged(bool hasVideo) 2103 2104 Emitted whenever the return value of hasVideo() changes, i.e., 2105 the media source being played back contains video. 2106 2107 Normally you'll check hasVideo() first and then let this signal 2108 tell you whether video is available now or not. That way you 2109 don't have to poll hasVideo(). 2110 2111 \a hasVideo is true when the stream contains video and adding a 2112 VideoWidget will show a video, and false if there is no video data 2113 in the stream and adding a VideoWidget will show an empty (black) 2114 VideoWidget. 2115*/ 2116 2117/*! 2118 \fn void Phonon::MediaObject::bufferStatus(int percentFilled) 2119 2120 Provides information about the status of the buffer. 2121 2122 When a MediaObject is in the \l{Phonon::}{BufferingState}, it will 2123 send this signal regularly. \a percentFilled is a number between 0 2124 and 100 telling you how much the buffer is filled. 2125 2126 You can use this signal to show a progress bar to the user when 2127 in BufferingState: 2128 2129 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 15 2130 2131 Note that the \l{Phonon::}{BufferingState} is commonly used when 2132 waiting for data over a network connection, but this might not be 2133 true for all backends. 2134*/ 2135 2136/*! 2137 \fn void Phonon::MediaObject::finished() 2138 2139 Emitted when the object has finished playback. It is not emitted 2140 if you call stop(), pause() or load(). It is emitted only when the 2141 current media source has finished playing and the media queue() is 2142 empty, or when a \l{Phonon::FatalError}{fatal error} occurs. 2143 2144 \warning This signal is not emitted when the current source has 2145 finished and there's another source in the queue. It is only 2146 emitted when the queue is empty. 2147 2148 \sa currentSourceChanged(), aboutToFinish(), prefinishMarkReached() 2149*/ 2150 2151/*! 2152 \fn void Phonon::MediaObject::currentSourceChanged(const Phonon::MediaSource &newSource) 2153 2154 Emitted when the MediaObject fetches a new MediaSource from the 2155 queue() and before it enters the \l{Phonon::}{LoadingState} for 2156 the new source. The media object will take a new source from the 2157 queue() when it has finished the playback of the 2158 \l{currentSource()}{current source}. 2159 2160 \a newSource is the source that starts to play at the time the 2161 signal is emitted. 2162*/ 2163 2164/*! 2165 \fn void Phonon::MediaObject::aboutToFinish() 2166 2167 Emitted before the playback of the whole queue ends. When this 2168 signal is emitted you still have time to enqueue() a new 2169 MediaSource, so that playback continues. 2170 2171 If you need a signal to be emitted at a specific time before 2172 playback is finished, you should use the prefinishMarkReached() 2173 signal instead. 2174 2175 \sa enqueue(), prefinishMark, prefinishMarkReached() 2176*/ 2177 2178/*! 2179 \fn void Phonon::MediaObject::prefinishMarkReached(qint32 msecToEnd) 2180 2181 Emitted when there are only \a msecToEnd milliseconds left 2182 of playback. 2183 2184 \warning This signal is not emitted when there is another source 2185 in the queue. It is only emitted when the queue is empty. 2186 2187 \sa setPrefinishMark(), prefinishMark(), aboutToFinish(), finished() 2188*/ 2189 2190/*! 2191 \fn void Phonon::MediaObject::totalTimeChanged(qint64 newTotalTime) 2192 2193 This signal is emitted as soon as the total time of the media file is 2194 known or has changed. For most non-local media data the total 2195 time of the media can only be known after some time. At that time the 2196 totalTime function can not return useful information. You have 2197 to wait for this signal to know the real total time. 2198 2199 \a newTotalTime is the length of the media file in milliseconds. 2200 2201 \sa totalTime() 2202*/ 2203 2204/*! 2205 \fn MediaObject *Phonon::createPlayer(Phonon::Category category, const MediaSource &source = MediaSource()) 2206 2207 Convenience function to create a MediaObject and AudioOutput 2208 connected by a path. The \l{Phonon::}{MediaObject} return will 2209 have \a source set as its current source and the specified \a 2210 category. 2211 2212*/ 2213 2214/*! 2215 \class Phonon::MediaObjectPrivate 2216 \inmodule Phonon 2217 \since 4.4 2218 \internal 2219*/ 2220 2221/*! 2222 \namespace Phonon::BackendCapabilities 2223 \inmodule Phonon 2224 \since 4.4 2225 \brief The BackendCapabilities namespace contains functions to describe the capabilities of the multimedia backend. 2226 2227*/ 2228 2229/*! 2230 \class Phonon::BackendCapabilitiesPrivate 2231 \inmodule Phonon 2232 \since 4.4 2233 \internal 2234*/ 2235 2236/*! 2237 \class Phonon::BackendCapabilities::Notifier 2238 \since 4.4 2239 \inmodule Phonon 2240 \inheaderfile Phonon/BackendCapabilities 2241 2242 Notifications about backend capabilities. 2243*/ 2244 2245/*! 2246 \fn void Phonon::BackendCapabilities::Notifier::capabilitiesChanged() 2247 2248 This signal is emitted if the capabilities have changed. This can 2249 happen if the user has requested a backend change. 2250*/ 2251 2252/*! 2253 \fn void Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged() 2254 2255 This signal is emitted when audio output devices were plugged or 2256 unplugged. 2257 2258 Check BackendCapabilities::availableAudioOutputDevices to get the 2259 current list of available devices. 2260*/ 2261 2262/*! 2263 \fn Notifier *Phonon::BackendCapabilities::notifier() 2264 2265 Use this function to get a QObject pointer to connect to the capabilitiesChanged signal. 2266 2267 \return a pointer to a QObject. 2268 2269 The capabilitiesChanged signal is emitted if the capabilities have changed. This can 2270 happen if the user has requested a backend change. 2271 2272 To connect to this signal do the following: 2273 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 16 2274 2275 \sa Notifier::capabilitiesChanged() 2276*/ 2277 2278/*! 2279 \fn QStringList Phonon::BackendCapabilities::availableMimeTypes() 2280 2281 Returns a list of mime types that the Backend can decode. 2282 2283 \sa isMimeTypeAvailable() 2284*/ 2285 2286/*! 2287 \fn bool Phonon::BackendCapabilities::isMimeTypeAvailable(const QString &mimeType) 2288 2289 Often all you want to know is whether one given MIME type can be 2290 decoded by the backend. Use this method in favor of 2291 availableMimeTypes() as it can give you a negative answer without 2292 having a backend loaded. 2293 2294 Returns true if the given \a mimeType is supported by the backend; 2295 otherwise, returns false. 2296 2297 \sa availableMimeTypes() 2298*/ 2299 2300/*! 2301 \fn QList<AudioOutputDevice> Phonon::BackendCapabilities::availableAudioOutputDevices() 2302 2303 Returns the audio output devices the backend supports. 2304 2305 \return A list of AudioOutputDevice objects that give a name and 2306 description for every supported audio output device. 2307*/ 2308 2309/*! 2310 \fn QList<EffectDescription> Phonon::BackendCapabilities::availableAudioEffects() 2311 2312 Returns descriptions for the audio effects the backend supports. 2313 2314 \return A list of AudioEffectDescription objects that give a name and 2315 description for every supported audio effect. 2316*/ 2317 2318/*! 2319 \internal 2320 \class ObjectDescriptionModelData 2321 \internal 2322 \inmodule Phonon 2323 \brief Data class for models for ObjectDescription objects. 2324*/ 2325 2326/*! 2327 \typedef Phonon::EffectDescription 2328 \relates Phonon::ObjectDescription 2329 2330 EffectDescription gives a description of an \l{Processors}{audio 2331 effect}. It is a typedef of the \l{Phonon::}{ObjectDescription} 2332 class. Please see its class description for details. 2333 2334 EffectDescription is used to create audio \l{Phonon::}{Effect}s, 2335 which can be inserted into a media graph, altering an audio 2336 stream. 2337 2338 \sa Phonon::ObjectDescription, {Capabilities Example}, {Media 2339 Player} 2340 2341*/ 2342 2343/*! 2344 \class Phonon::ObjectDescriptionModel 2345 \inmodule Phonon 2346 \internal 2347 \since 4.4 2348 \brief The ObjectDescriptionModel class provides a model from 2349 a list of ObjectDescription objects. 2350 2351 ObjectDescriptionModel is a read only model that supplies a list 2352 using ObjectDescription::name() for the text and 2353 ObjectDescription::description() for the tooltip. If set the properties 2354 "icon" and "available" are used to set the decoration and disable the 2355 item (disabled only visually, you can still select and drag it). 2356 2357 It also provides the methods moveUp() and moveDown() to order the list. 2358 Additionally drag and drop is possible so that 2359 QAbstractItemView::InternalMove can be used. 2360 The resulting order of the ObjectDescription::index() values can then be 2361 retrieved using tupleIndexOrder(). 2362 2363 An example use case would be to give the user a QComboBox to select 2364 the output device: 2365 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 17 2366 2367 And to retrieve the selected AudioOutputDevice: 2368 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 18 2369 2370*/ 2371 2372/*! 2373 \fn inline int Phonon::ObjectDescriptionModel::rowCount(const QModelIndex &parent = QModelIndex()) const 2374 2375 Returns the number of rows in the model. This value corresponds 2376 to the size of the list passed through setModelData. 2377 2378 \param parent The optional \a parent argument is used in most models to specify 2379 the parent of the rows to be counted. Because this is a list if a 2380 valid parent is specified the result will always be 0. 2381 2382 Reimplemented from QAbstractItemModel. 2383 2384 \sa QAbstractItemModel::rowCount() 2385*/ 2386 2387/*! 2388 \fn inline QVariant Phonon::ObjectDescriptionModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const 2389 2390 Returns data from the item with the given \a index for the specified 2391 \a role. 2392 If the view requests an invalid index, an invalid variant is 2393 returned. 2394 2395 Reimplemented from QAbstractItemModel. 2396 2397 \sa QAbstractItemModel::data(), Qt::ItemDataRole 2398*/ 2399 2400/*! 2401 \fn inline Qt::ItemFlags Phonon::ObjectDescriptionModel::flags(const QModelIndex &index) const 2402 \internal 2403 2404 Reimplemented to show unavailable devices as disabled (but still 2405 selectable). The \a index of the model index for which to return 2406 flags. 2407 2408*/ 2409 2410/*! 2411 \fn inline QList<int> Phonon::ObjectDescriptionModel::tupleIndexOrder() const 2412 2413 Returns a list of indexes in the same order as they are in the 2414 model. The indexes come from the ObjectDescription::index 2415 method. 2416 2417 This is useful to let the user define a list of preference. 2418*/ 2419 2420/*! 2421 \fn inline int Phonon::ObjectDescriptionModel::tupleIndexAtPositionIndex(int positionIndex) const 2422 2423 Returns the ObjectDescription::index for the tuple 2424 at the given position \a positionIndex. For example a 2425 QComboBox will give you the currentIndex as the 2426 position in the list. But to select the according 2427 AudioOutputDevice using AudioOutputDevice::fromIndex 2428 you can use this method. 2429 2430 \param positionIndex The position in the list. 2431*/ 2432 2433/*! 2434 \class Phonon::ObjectDescriptionModelDataPrivate 2435 \inmodule Phonon 2436 \since 4.4 2437 \internal 2438*/ 2439 2440/*! 2441 \fn inline QMimeData *Phonon::ObjectDescriptionModel::mimeData(const QModelIndexList &indexes) const 2442 \internal 2443 2444 Returns the MIME data that dropMimeData() can use to create new 2445 items. 2446*/ 2447 2448/*! 2449 \fn inline void Phonon::ObjectDescriptionModel::moveUp(const QModelIndex &index) 2450 2451 Moves the item at the given \a index up. In the resulting list 2452 the items at index.row() and index.row() - 1 are swapped. 2453 2454 Connected views are updated automatically. 2455*/ 2456 2457/*! 2458 \fn inline void Phonon::ObjectDescriptionModel::moveDown(const QModelIndex &index) 2459 2460 Moves the item at the given \a index down. In the resulting list 2461 the items at index.row() and index.row() + 1 are swapped. 2462 2463 Connected views are updated automatically. 2464*/ 2465 2466/*! 2467 \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(QObject *parent = 0) 2468 2469 Constructs a ObjectDescription model with the 2470 given \a parent. 2471*/ 2472 2473/*! 2474 \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(const QList<ObjectDescription<type> > &data, QObject *parent = 0) 2475 2476 Constructs a ObjectDescription model with the 2477 given \a parent and the given \a data. 2478*/ 2479 2480/*! 2481 \fn inline void Phonon::ObjectDescriptionModel::setModelData(const QList<ObjectDescription<type> > &data) 2482 2483 Sets the model data using the list provided by \a data. 2484 2485 All previous model data is cleared. 2486*/ 2487 2488/*! 2489 \fn inline QList<ObjectDescription<type> > Phonon::ObjectDescriptionModel::modelData() const 2490 2491 Returns the model data. 2492 2493 As the order of the list might have changed this can be different 2494 to what was set using setModelData(). 2495*/ 2496 2497/*! 2498 \fn inline ObjectDescription<type> Phonon::ObjectDescriptionModel::modelData(const QModelIndex &index) const 2499 2500 Returns one ObjectDescription of the model data for the given \a index. 2501*/ 2502 2503/*! 2504 \fn inline Qt::DropActions Phonon::ObjectDescriptionModel::supportedDropActions() const 2505 2506 This model supports drag and drop to copy or move 2507 items. 2508*/ 2509 2510/*! 2511 \fn inline bool Phonon::ObjectDescriptionModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) 2512 2513 Accept drops from other models of the same ObjectDescriptionType. 2514 2515 The \a data is dropped at the given \a row and \a column; you 2516 also receive the \a parent model index. 2517 2518 If a valid \a parent is given the dropped items will be inserted 2519 above that item. 2520*/ 2521 2522/*! 2523 \fn inline bool Phonon::ObjectDescriptionModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex()) 2524 2525 Removes count rows starting with the given row. 2526 2527 If a valid \a parent is given no rows are removed since this is a 2528 list model. 2529 2530 Returns true if the rows were successfully removed; otherwise returns false. 2531*/ 2532 2533/*! 2534 \fn inline QStringList Phonon::ObjectDescriptionModel::mimeTypes() const 2535 2536 Returns a list of supported drag and drop MIME types. Currently 2537 it only supports one type used internally. 2538*/ 2539 2540/*! 2541 \class Phonon::EffectInterface 2542 \inmodule Phonon 2543 \since 4.4 2544 \internal 2545*/ 2546 2547/*! 2548 \class Phonon::Effect 2549 \inmodule Phonon 2550 \inheaderfile Phonon/Effect 2551 \since 4.4 2552 \brief The Effect class is used to transform audio streams. 2553 2554 An effect is a media node which is inserted into a path between a 2555 \l{Phonon::}{MediaObject} and an audio output node, for instance, 2556 an \l{Phonon::}{AudioOutput}. The Effect transforms the media 2557 stream on that path. 2558 2559 Examples may include simple modifiers, such as fading or pitch 2560 shifting, and more complex mathematical transformations. You can 2561 query the backend for available effects with 2562 BackendCapabilities::availableAudioEffects(). Note that the 2563 effects available is dependent on the underlying system 2564 (DirectDraw, GStreamer, or QuickTime). 2565 2566 In order to use an effect, insert it into the path as follows: 2567 2568 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 19 2569 2570 The effect will immediately begin applying it's transformations on 2571 the path. To stop it, remove the Effect from the path. 2572 2573 To create an effect, you use the \l{Phonon::}{EffectDescription} 2574 class, which you get from 2575 \l{BackendCapabilities::}{availableAudioEffects()}. We give a code 2576 example below. 2577 2578 \snippet doc/src/snippets/audioeffects.cpp 0 2579 2580 An effect can have one or more parameters, which let you alter how 2581 the effect works, for instance, by specifying the depth of a 2582 reverb effect. See the EffectParameter class description for 2583 details. 2584 2585 Phonon also provides EffectWidget, which lets the user modify the 2586 parameters of an effect an the fly; e.g., with combo boxes. 2587 2588 \sa {Phonon Module}, EffectWidget 2589*/ 2590 2591/*! 2592 \fn explicit Phonon::Effect::Effect(const EffectDescription &description, QObject *parent = 0) 2593 2594 Constructs a new effect object with the given \a description and \a parent object. 2595 2596 The EffectDescription object determines the type of the effect. 2597 2598 \sa {Phonon::BackendCapabilities::availableAudioEffects()} 2599*/ 2600 2601/*! 2602 \fn Phonon::Effect::Effect(EffectPrivate &dd, QObject *parent) 2603 \internal 2604*/ 2605 2606/*! 2607 \fn Phonon::Effect::~Effect() 2608 \internal 2609*/ 2610 2611/*! 2612 \fn QVariant Phonon::Effect::parameterValue(const EffectParameter ¶meter) const 2613 2614 Returns the value of the given effect \a parameter. You can fetch 2615 the available parameters for an effect with parameters(). 2616 2617 \sa setParameterValue(), EffectParameter 2618*/ 2619 2620/*! 2621 \fn void Phonon::Effect::setParameterValue(const EffectParameter ¶meter, const QVariant &value) 2622 2623 Sets the given effect \a parameter to the specified \a value. 2624 2625 Parameters for an effect are returned by parameters(). You can 2626 check which QVariant::Type an EffectParameter takes with the 2627 EffectParameter::type() function. 2628 2629 \sa parameterValue(), EffectParameter 2630*/ 2631 2632/*! 2633 \fn EffectDescription Phonon::Effect::description() const; 2634 2635 Returns the description of this effect. This is the same 2636 description that was passed to the constructor. 2637*/ 2638 2639/*! 2640 \fn QList<EffectParameter> Phonon::Effect::parameters() const; 2641 2642 Returns a list of parameters that this effect provides to control 2643 its behavior. 2644 2645 \sa EffectParameter, EffectWidget 2646*/ 2647 2648/*! 2649 \class Phonon::EffectPrivate 2650 \inmodule Phonon 2651 \since 4.4 2652 \internal 2653*/ 2654 2655/*! 2656 \class Phonon::AudioOutput 2657 \inmodule Phonon 2658 \inheaderfile Phonon/AudioOutput 2659 \since 4.4 2660 \brief The AudioOutput class is used to send data to audio output devices. 2661 2662 The AudioOutput class plays sound over a sound device. The audio 2663 output needs to be connected to a \l{Phonon::}{MediaObject} using 2664 \l{Phonon::}{createPath()}. To start playback, you call 2665 \l{Phonon::MediaObject::}{play()} on the media object. 2666 2667 \snippet snippets/phonon.cpp 2 2668 2669 The class supports changing the volume(). It is also possible to 2670 mute the sound. 2671 2672 To find out what \l{Phonon::}{AudioOutputDevice}s are available 2673 for AudioOutput, you can call 2674 BackendCapabilities::availableAudioOutputDevices(). A default device is 2675 selected by the backend, but it is possible to set the device to 2676 be used with setOutputDevice(). The outputDeviceChanged() signal 2677 will be emitted if the device changes. 2678 2679 If an error occurs with the playback, for instance, if no valid 2680 output device is found, the media object will receive a 2681 stateChanged() signal with the \l{Phonon::}{ErrorState}. 2682 2683 Note that the default values of properties are dependent on the 2684 backend. 2685 2686 \sa Phonon::VolumeSlider, {Music Player Example}, BackendCapabilities, {Phonon Module} 2687*/ 2688 2689/*! 2690 \property Phonon::AudioOutput::name 2691 2692 This is the name that appears in Mixer applications that control 2693 the volume of this output. 2694 2695*/ 2696 2697/*! 2698 \property Phonon::AudioOutput::volume 2699 2700 This is the current loudness of the output. \omit The volume is a 2701 real value between 0.0 (minimum) and 1.0 (maximum). The volume 2702 follows the sound device used, with 1.0 being the maximum volume 2703 the device can produce. \endomit 2704 2705 (it is using Stevens' law 2706 to calculate the change in voltage internally). 2707 2708 \sa volumeDecibel 2709*/ 2710 2711/*! 2712 \property Phonon::AudioOutput::volumeDecibel 2713 2714 This is the current volume of the output in decibel. 2715 2716 0 dB means no change in volume, -6dB means an attenuation of the 2717 voltage to 50% and an attenuation of the power to 25%, -inf dB means 2718 silence. 2719 2720 \sa volume 2721*/ 2722 2723/*! 2724 \property Phonon::AudioOutput::outputDevice 2725 This property holds the (hardware) destination for the output. 2726 2727 The default device is determined by the \l{Phonon::}{Category} and the global 2728 configuration for that category. Normally you don't need 2729 to override this setting - letting the user change the global 2730 configuration is the right choice. You can still override the 2731 device though, if you have good reasons to do so. 2732 2733 \sa outputDeviceChanged() 2734*/ 2735 2736/*! 2737 \property Phonon::AudioOutput::muted 2738 This property tells whether the output is muted. 2739 2740 Muting the output has the same effect as calling setVolume(0.0). 2741*/ 2742 2743/*! 2744 \fn explicit Phonon::AudioOutput::AudioOutput(Phonon::Category category, QObject *parent = 0) 2745 2746 Creates a new AudioOutput with the given \a parent that defines 2747 output to a physical device. 2748 2749 The \a category can be used by mixer applications to group volume 2750 controls of applications into categories. That makes it easier for 2751 the user to identify the programs. 2752 The category is also used for the default output device that is 2753 configured centrally. As an example: often users want to have the 2754 audio signal of a VoIP application go to their USB headset while 2755 all other sounds should go to the internal soundcard. 2756 2757 \sa Phonon::categoryToString(), outputDevice 2758*/ 2759 2760/*! 2761 \fn explicit Phonon::AudioOutput::AudioOutput(QObject *parent = 0) 2762 2763 Creates a new AudioOutput that defines output to the system 2764 default device with the \{Phonon::Category::}{NoCategory} category 2765 2766 \sa Phonon::categoryToString(), outputDevice 2767*/ 2768 2769/*! 2770 \fn Phonon::Category Phonon::AudioOutput::category() const 2771 2772 Returns the category of this output. 2773 2774 \sa Phonon::AudioOutput::AudioOutput() 2775*/ 2776 2777/*! 2778 \fn void Phonon::AudioOutput::volumeChanged(qreal newVolume) 2779 2780 This signal is emitted whenever the volume has changed. As the 2781 volume can change without a call to setVolume (calls over dbus) 2782 this is important to keep a widget showing the current volume up 2783 to date. 2784 2785 \a newVolume is the new volume level. 2786 2787 \sa setVolume(), volume() 2788*/ 2789 2790/*! 2791 \fn void Phonon::AudioOutput::mutedChanged(bool muted) 2792 2793 This signal is emitted when the muted property has changed. The \a muted 2794 value passed by the signal indicates the state of the muted property. 2795 As this property can change by IPC (DBus) calls a UI element showing 2796 the muted property should listen to this signal. 2797*/ 2798 2799/*! 2800 \fn void Phonon::AudioOutput::outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice) 2801 2802 This signal is emitted when the (hardware) device for the output 2803 has changed. \a newAudioOutputDevice is the new device. 2804 2805 The change can happen either through setOutputDevice or if the 2806 global configuration for the used category has changed. 2807 2808 \sa outputDevice 2809*/ 2810 2811/*! 2812 \class Phonon::AudioOutputPrivate 2813 \inmodule Phonon 2814 \since 4.4 2815 \internal 2816*/ 2817 2818/*! 2819 \class Phonon::EffectParameter 2820 \inmodule Phonon 2821 \inheaderfile Phonon/EffectParameter 2822 \since 4.4 2823 \brief The EffectParameter class describes one parameter of an effect. 2824 2825 You fetch the parameters of an \l{Phonon::}{Effect} with 2826 \l{Phonon::}{Effect::parameters()}. 2827 2828 \snippet doc/src/snippets/phononeffectparameter.cpp 0 2829 2830 To describe itself, an effect parameter gives a name() and 2831 possibly description() (depending on the backend used). These are 2832 suited to present the effect parameter to the user of a Phonon 2833 application. 2834 2835 Note that effects are created by the backend, and that 2836 their name and descriptions may vary. 2837 2838 The value of an effect parameter is stored in a \l{QVariant}, 2839 of which type() is usually \c int or \c double. 2840 2841 The value is retrieved with \l{Phonon::}{Effect::parameterValue()} 2842 and set with \l{Phonon::Effect::}{setParameterValue()} - both of 2843 which takes the EffectParameter as argument. Note that not all 2844 effect parameters support setting of their value. 2845 2846 You get the values a parameter can take with possibleValues(); an 2847 empty list is returned if the values are continuous. 2848 2849 A parameter may also specify default(), minimum(), and maximum() 2850 values. Values are returned as \l{QVariant}s. If the parameter 2851 does not have the requested value, an \l{QVariant::Invalid} 2852 invalid QVariant is returned from these functions. 2853 2854 The \l{Phonon::}{EffectWidget} provides a widget with which one 2855 can control the parameters of an \l{Phonon::}{Effect}. 2856 2857 \snippet doc/src/snippets/phononeffectparameter.cpp 1 2858 2859 \sa Effect, EffectWidget, {Capabilities Example}, {Phonon Module} 2860*/ 2861 2862/*! 2863 \fn Phonon::EffectParameter::EffectParameter() 2864 \internal 2865 2866 Creates an invalid effect parameter. 2867*/ 2868 2869/*! 2870 \fn Phonon::EffectParameter::~EffectParameter() 2871 2872 Destroys the effect parameter. 2873*/ 2874 2875/*! 2876 \fn Phonon::EffectParameter::EffectParameter(const EffectParameter &other) 2877 2878 Constructs a copy of the \a other effect parameter. 2879*/ 2880 2881/*! 2882 \fn const QString &Phonon::EffectParameter::name() const 2883 2884 The name of the parameter. Can be used as the label. 2885 2886 \return A label for the parameter. 2887*/ 2888 2889/*! 2890 \fn const QString &Phonon::EffectParameter::description() const 2891 2892 The parameter may come with a description (LADSPA doesn't have a 2893 field for this, so don't expect many effects to provide a 2894 description). 2895 2896 The description can be used for a tooltip or WhatsThis help. 2897 2898 \return A text describing the parameter. 2899*/ 2900 2901/*! 2902 \fn QVariant::Type Phonon::EffectParameter::type() const 2903 2904 Returns the parameter type. 2905 2906 Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When 2907 QVariant::String is returned you get the possible values from possibleValues. 2908*/ 2909 2910/*! 2911 \fn bool Phonon::EffectParameter::isLogarithmicControl() const 2912 2913 Returns whether the parameter should be 2914 displayed using a logarithmic scale. This is particularly useful for 2915 frequencies and gains. 2916*/ 2917 2918/*! 2919 \fn QVariant Phonon::EffectParameter::minimumValue() const 2920 2921 The minimum value to be used for the control to edit the parameter. 2922 2923 If the returned QVariant is invalid the value is not bounded from 2924 below. 2925*/ 2926 2927/*! 2928 \fn QVariant Phonon::EffectParameter::maximumValue() const 2929 2930 The maximum value to be used for the control to edit the parameter. 2931 2932 If the returned QVariant is invalid the value is not bounded from 2933 above. 2934*/ 2935 2936/*! 2937 \fn QVariant Phonon::EffectParameter::defaultValue() const 2938 2939 The default value. 2940*/ 2941 2942/*! 2943 \fn QVariantList Phonon::EffectParameter::possibleValues() const 2944 2945 The possible values to be used for the control to edit the parameter. 2946 2947 if the value of this parameter is to be picked from predefined values 2948 this returns the list (otherwise it returns an empty QVariantList). 2949*/ 2950 2951/*! 2952 \fn bool Phonon::EffectParameter::operator<(const EffectParameter &rhs) const 2953 2954 \internal 2955 compares the ids of the parameters 2956*/ 2957 2958/*! 2959 \fn bool Phonon::EffectParameter::operator>(const EffectParameter &rhs) const 2960 2961 \internal 2962 compares the ids of the parameters 2963*/ 2964 2965/*! 2966 \fn bool Phonon::EffectParameter::operator==(const EffectParameter &rhs) const 2967 2968 \internal 2969 compares the ids of the parameters 2970*/ 2971 2972/*! 2973 \fn Phonon::EffectParameter &Phonon::EffectParameter::operator=(const EffectParameter &other) 2974 2975 Assigns the \a other effect parameter to this parameter and returns 2976 a reference to this parameter. 2977*/ 2978 2979/*! 2980 \enum Phonon::EffectParameter::Hint 2981 2982 Only for backend developers: 2983 2984 Flags to set the return values of isToggleControl(), 2985 isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and 2986 isBoundedAbove(). The values of the flags correspond to the values 2987 used for LADSPA effects. 2988 2989 \value ToggledHint 2990 If this hint is set it means that 2991 the control has only two states: zero and non-zero 2992 (see isToggleControl()). 2993 2994 \value LogarithmicHint 2995 LADSPA's SAMPLE_RATE hint needs to be translated by the backend 2996 to normal bounds, as the backend knows the sample rate - and the 2997 frontend doesn't (see isLogarithmicControl()). 2998 2999 \value IntegerHint See isIntegerControl(). 3000*/ 3001 3002/*! 3003 \fn Phonon::EffectParameter::EffectParameter(int parameterId, 3004 const QString &name, EffectParameter::Hints hints, 3005 const QVariant &defaultValue, const QVariant &min = QVariant(), 3006 const QVariant &max = QVariant(), const QVariantList &values = QVariantList(), 3007 const QString &description = QString()) 3008 3009 Only to be used by backend implementations: 3010 3011 Creates a new effect parameter. 3012 3013 \a parameterId This is a number to uniquely identify the 3014 parameter. The id is used for value() and setValue(). 3015 3016 \a name is the name/label for this parameter. 3017 3018 \a hints sets the hints for the type of parameter. 3019 3020 \a defaultValue The value that should be used as a default. 3021 3022 \a min is the minimum value allowed for this parameter. You only 3023 need to set this if the BoundedBelowHint is set. 3024 3025 \a max is the maximum value allowed for this parameter. You only 3026 need to set this if the BoundedAboveHint is set. 3027 3028 The \a values parameter is the values that the effect parameter 3029 can take (only applies if non-continuous) 3030 3031 \a description is a descriptive text for the parameter 3032 (explaining what it controls) to be used as a tooltip or 3033 WhatsThis help. 3034*/ 3035 3036/*! 3037 \fn int Phonon::EffectParameter::id() const 3038 3039 \internal 3040 3041 Returns the parameter's identifier. 3042*/ 3043 3044/*! 3045 \typedef Phonon::AudioOutputInterface 3046 \inmodule Phonon 3047 \internal 3048*/ 3049 3050/*! 3051 \class Phonon::AudioOutputInterface40 3052 \inmodule Phonon 3053 \since 4.4 3054 \internal 3055 \brief Interface for AudioOutput objects 3056 3057*/ 3058 3059/*! 3060 \fn virtual Phonon::AudioOutputInterface40::~AudioOutputInterface40() 3061 \internal 3062*/ 3063 3064/*! 3065 \fn virtual qreal Phonon::AudioOutputInterface40::volume() const = 0 3066 \internal 3067*/ 3068 3069/*! 3070 \fn virtual void Phonon::AudioOutputInterface40::setVolume(qreal) = 0 3071 \internal 3072*/ 3073 3074/*! 3075 \fn virtual int Phonon::AudioOutputInterface40::outputDevice() const = 0 3076 \internal 3077*/ 3078 3079/*! 3080 \fn virtual bool Phonon::AudioOutputInterface40::setOutputDevice(int) = 0 3081 \internal 3082*/ 3083 3084/*! 3085 \class Phonon::Path 3086 \inmodule Phonon 3087 \inheaderfile Phonon/Path 3088 \since 4.4 3089 \brief The Path class describes connections between media nodes. 3090 3091 In a \l{Building Graphs}{media graph}, \l{Phonon::}{MediaNode}s 3092 are connected by Paths. The multimedia travels in streams over 3093 these paths. 3094 3095 You create a path between two media nodes using the static 3096 Phonon::createPath() function, which takes two nodes as arguments. 3097 The first argument will send the media stream to the second. 3098 Please refer to the class description of the individual media 3099 nodes and the Phonon \l{Phonon Overview}{overview} to see which 3100 nodes can be connected to each other. 3101 3102 Paths are also used to insert audio \l{Phonon::}{Effect}s between 3103 two media nodes. The effect will then alter the stream on the 3104 path. Notice that \l{Phonon::}{Effect}s also are media nodes, but 3105 that insertEffect() - instead of Phonon::createPath() - is used to 3106 insert them into the media graph. 3107 3108 The following code example shows how to create a path between two 3109 media nodes and insert an effect on that path. 3110 3111 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 20 3112 3113 \sa Phonon::MediaNode, Phonon::MediaObject, Phonon::AudioOutput, 3114 Phonon::VideoWidget, {Phonon Module} 3115*/ 3116 3117/*! 3118 \fn Phonon::Path::~Path(); 3119 3120 Destroys this reference to the Path. If the path was valid the connection is not broken 3121 as both the source and the sink MediaNodes still keep a reference to the Path. 3122 3123 \sa disconnect() 3124*/ 3125 3126/*! 3127 \fn Phonon::Path::Path(); 3128 3129 Creates an invalid path. 3130 3131 You can still make it a valid path by calling reconnect. It is 3132 recommended to use the Phonon::createPath() function to create 3133 paths. 3134 3135 \sa Phonon::createPath(), isValid() 3136*/ 3137 3138/*! 3139 \fn Phonon::Path::Path(const Path &path); 3140 3141 Constructs a copy of the other \a path specified. 3142 3143 This constructor is fast thanks to explicit sharing. 3144*/ 3145 3146/*! 3147 \fn bool Phonon::Path::isValid() const; 3148 3149 A path is considered valid if it is connected to two media nodes, 3150 in which case this function returns true. If it is connected to 3151 one or no media nodes, it is consider invalid, and this function 3152 will then return false. 3153*/ 3154 3155/*! 3156 \fn Effect *Phonon::Path::insertEffect(const EffectDescription &desc, Effect *insertBefore = 0); 3157 3158 Creates and inserts an effect into the path. 3159 3160 You may insert effects of the same class as often as you like, 3161 but if you insert the same object, the call will fail. 3162 3163 \a desc is the EffectDescription object for the effect to be inserted. 3164 3165 If you already inserted an effect you can 3166 tell with \a insertBefore in which order the data gets 3167 processed. If this is \c 0 the effect is appended at the end of 3168 the processing list. If the effect has not been inserted before 3169 the method will do nothing and return \c false. 3170 3171 Returns a pointer to the effect object if it could be inserted 3172 at the specified position. If \c 0 is returned, the effect was not 3173 inserted. 3174 3175 Below is a code example for inserting an effect into a path: 3176 3177 \snippet doc/src/snippets/audioeffects.cpp 0 3178 3179 \sa removeEffect(), effects() 3180*/ 3181 3182/*! 3183 \fn bool Phonon::Path::insertEffect(Effect *effect, Effect *insertBefore = 0); 3184 3185 Inserts the given \a effect into the path before the effect specified by \a insertBefore 3186 and returns true if successful; otherwise returns false. 3187 3188 If \a insertBefore is zero, the effect is appended to the processing list. 3189 3190 You may insert effects of the same class as often as you like, but if you insert 3191 the same object, the call will fail. 3192 3193 \a effect will be inserted right before \a insertBefore. If 3194 \a insertBefore is \c 0, the effect is appended at the end of the 3195 processing list. If the effect has not been inserted before the 3196 method will do nothing and return \c false. 3197 3198 Returns whether the effect could be inserted at the specified 3199 position. If \c false is returned the effect was not inserted. 3200 3201 \sa removeEffect(), effects() 3202*/ 3203 3204/*! 3205 \fn bool Phonon::Path::removeEffect(Effect *effect); 3206 3207 Removes the given \a effect from the path and returns true; otherwise returns false. 3208 3209 Removes an \a effect from the path. 3210 3211 If the effect is deleted while it is still connected, the effect will be removed 3212 automatically. 3213 3214 \omit 3215 \param effect The effect to be removed. 3216 3217 \return Returns whether the call was successful. If it returns 3218 \c false the effect could not be found in the path, meaning it 3219 has not been inserted before. 3220 \endomit 3221 3222 \sa insertEffect(), effects() 3223*/ 3224 3225/*! 3226 \fn QList<Effect *> Phonon::Path::effects() const; 3227 3228 Returns a list of Effect objects that are currently 3229 used as effects. The order in the list determines the order the 3230 signal is sent through the effects. 3231 3232 \return A list with all current effects. 3233 3234 \sa insertEffect(), removeEffect() 3235*/ 3236 3237/*! 3238 \fn bool Phonon::Path::reconnect(MediaNode *source, MediaNode *sink); 3239 3240 Changes the media nodes the path is connected to by connecting the path 3241 to the \a source and \a sink nodes specified. Returns true if successful; 3242 otherwise returns false. 3243 3244 If unsuccessful, the path remains connected to the same nodes as before. 3245 3246 \sa Phonon::createPath(), {Phonon Overview} 3247*/ 3248 3249/*! 3250 \fn bool Phonon::Path::disconnect(); 3251 3252 Tries to disconnect the path from the MediaNodes it is connected to, returning 3253 true if successful or false if unsuccessful. 3254 3255 If successful, the path is invalidated: isValid() will returns false. 3256*/ 3257 3258/*! 3259 \fn Path &Phonon::Path::operator=(const Path &p); 3260 3261 Assigns \a p to this Path and returns a reference to this Path. 3262 3263 This operation is fast thanks to explicit sharing. 3264*/ 3265 3266/*! 3267 \fn bool Phonon::Path::operator==(const Path &p) const; 3268 3269 Returns true if this Path is equal to \a p; otherwise returns false; 3270*/ 3271 3272/*! 3273 \fn bool Phonon::Path::operator!=(const Path &p) const; 3274 3275 Returns true if this Path is not equal to \a p; otherwise returns false. 3276*/ 3277 3278/*! 3279 \fn MediaNode *Phonon::Path::source() const; 3280 3281 Returns the source MediaNode used by the path. 3282*/ 3283 3284/*! 3285 \fn MediaNode *Phonon::Path::sink() const; 3286 3287 Returns the sink MediaNode used by the path. 3288*/ 3289 3290/*! 3291 \fn Path Phonon::createPath(MediaNode *source, MediaNode *sink); 3292 3293 \relates Phonon::Path 3294 Creates a new Path connecting the two MediaNodes \a source and \a sink. 3295 3296 The implementation will automatically select the right format and media type. E.g. connecting a 3297 MediaObject and AudioOutput will create a Path object connecting the audio. This might be 3298 represented as PCM or perhaps even AC3 depending on the AudioOutput object. 3299 3300 \param source The MediaNode to connect an output from 3301 \param sink The MediaNode to connect to. 3302*/ 3303 3304/*! 3305 \class Phonon::PathPrivate 3306 \inmodule Phonon 3307 \since 4.4 3308 \internal 3309*/ 3310 3311/*! 3312 \class Phonon::MediaObjectInterface 3313 \inmodule Phonon 3314 \since 4.4 3315 \internal 3316 \brief Backend interface for media sources. 3317 3318 The backend implementation has to provide two signals, that are not defined 3319 in this interface: 3320 \list 3321 \o \target phonon_MediaObjectInterface_stateChanged 3322 void stateChanged(Phonon::State newstate, Phonon::State oldstate) 3323 3324 Emitted when the state of the MediaObject has changed. 3325 In case you're not interested in the old state you can also 3326 connect to a slot that only has one State argument. 3327 3328 \param newstate The state the Player is in now. 3329 \param oldstate The state the Player was in before. 3330 3331 \o \target phonon_MediaObjectInterface_tick 3332 void tick(qint64 time) 3333 3334 This signal gets emitted every tickInterval milliseconds. 3335 3336 \param time The position of the media file in milliseconds. 3337 3338 \sa setTickInterval() 3339 \sa tickInterval() 3340 \endlist 3341 3342 \sa MediaObject 3343*/ 3344 3345/*! 3346 \fn virtual Phonon::MediaObjectInterface::~MediaObjectInterface() 3347 \internal 3348*/ 3349 3350/*! 3351 \fn virtual qint64 Phonon::MediaObjectInterface::remainingTime() const 3352 \internal 3353*/ 3354 3355/*! 3356 \fn virtual qint32 Phonon::MediaObjectInterface::prefinishMark() const = 0 3357 \internal 3358*/ 3359 3360/*! 3361 \fn virtual void Phonon::MediaObjectInterface::setPrefinishMark(qint32) = 0 3362 \internal 3363*/ 3364 3365/*! 3366 \fn virtual qint32 Phonon::MediaObjectInterface::transitionTime() const = 0 3367 \internal 3368*/ 3369 3370/*! 3371 \fn virtual void Phonon::MediaObjectInterface::setTransitionTime(qint32) = 0 3372 \internal 3373*/ 3374 3375/*! 3376 \fn virtual void Phonon::MediaObjectInterface::play() = 0 3377 \internal 3378 3379 Requests the playback to start. 3380 3381 This method is only called if the state transition to PlayingState is possible. 3382 3383 The backend should react immediately 3384 by either going into PlayingState or BufferingState if the 3385 former is not possible. 3386*/ 3387 3388/*! 3389 \fn virtual void Phonon::MediaObjectInterface::pause() = 0 3390 \internal 3391 3392 Requests the playback to pause. 3393 3394 This method is only called if the state transition to PausedState is possible. 3395 3396 The backend should react as fast as possible. Go to PausedState 3397 as soon as playback is paused. 3398*/ 3399 3400/*! 3401 \fn virtual void Phonon::MediaObjectInterface::stop() = 0 3402 \internal 3403 3404 Requests the playback to be stopped. 3405 3406 This method is only called if the state transition to StoppedState is possible. 3407 3408 The backend should react as fast as possible. Go to StoppedState 3409 as soon as playback is stopped. 3410 3411 A subsequent call to play() will start playback at the beginning of 3412 the media. 3413*/ 3414 3415/*! 3416 \fn virtual void Phonon::MediaObjectInterface::seek(qint64 milliseconds) = 0 3417 \internal 3418 3419 Requests the playback to be seeked to the given time. 3420 3421 The backend does not have to finish seeking while in this function 3422 (i.e. the backend does not need to block the thread until the seek is 3423 finished; even worse it might lead to deadlocks when using a 3424 ByteStream which gets its data from the thread this function would 3425 block). 3426 3427 As soon as the seek is done the currentTime() function and 3428 the tick() signal will report it. 3429 3430 \param milliseconds The time where playback should seek to in 3431 milliseconds. 3432*/ 3433 3434/*! 3435 \fn virtual qint32 Phonon::MediaObjectInterface::tickInterval() const = 0 3436 \internal 3437 3438 Return the time interval in milliseconds between two ticks. 3439 3440 Returns the tick interval that it was set to (might not 3441 be the same as you asked for). 3442*/ 3443 3444/*! 3445 \fn virtual void Phonon::MediaObjectInterface::setTickInterval(qint32 interval) = 0 3446 \internal 3447 3448 Change the interval the tick signal is emitted. Set \a interval to 0 to 3449 disable the signal. 3450 3451 \a interval tick interval in milliseconds 3452 3453 Returns the tick interval that it was set to (might not be the same as you 3454 asked for). 3455 3456*/ 3457 3458/*! 3459 \fn virtual bool Phonon::MediaObjectInterface::hasVideo() const = 0 3460 \internal 3461 3462 Check whether the media data includes a video stream. 3463 3464 Returns true if the media contains video data. 3465*/ 3466 3467/*! 3468 \fn virtual bool Phonon::MediaObjectInterface::isSeekable() const = 0 3469 \internal 3470 3471 If the current media may be seeked this function returns true; 3472 otherwise, false. 3473 3474 Returns whether the current media may be seeked. 3475*/ 3476 3477/*! 3478 \fn virtual qint64 Phonon::MediaObjectInterface::currentTime() const = 0 3479 \internal 3480 3481 Get the current time (in milliseconds) of the file currently being played. 3482*/ 3483 3484/*! 3485 \fn virtual Phonon::State Phonon::MediaObjectInterface::state() const = 0 3486 \internal 3487 3488 Get the current state. 3489*/ 3490 3491/*! 3492 \fn virtual QString Phonon::MediaObjectInterface::errorString() const = 0 3493 \internal 3494 3495 A translated string describing the error. 3496*/ 3497 3498/*! 3499 \fn virtual Phonon::ErrorType Phonon::MediaObjectInterface::errorType() const = 0 3500 \internal 3501 3502 Tells your program what to do about the error. 3503 3504 \sa Phonon::ErrorType 3505*/ 3506 3507/*! 3508 \fn virtual qint64 Phonon::MediaObjectInterface::totalTime() const = 0 3509 \internal 3510 3511 Returns the total time of the media in milliseconds. 3512 3513 If the total time is not know return -1. Do not block until it is 3514 known, instead emit the totalTimeChanged signal as soon as the total 3515 time is known or changes. 3516*/ 3517 3518/*! 3519 \fn virtual MediaSource Phonon::MediaObjectInterface::source() const = 0 3520 \internal 3521 3522 Returns the current source. 3523*/ 3524 3525/*! 3526 \fn virtual void Phonon::MediaObjectInterface::setSource(const MediaSource &) = 0 3527 \internal 3528 3529 Sets the current source. When this function is called the MediaObject is 3530 expected to stop all current activity and start loading the new 3531 source (i.e. go into LoadingState). 3532 3533 It is expected that the 3534 backend now starts preloading the media data, filling the audio 3535 and video buffers and making all media meta data available. It 3536 will also trigger the totalTimeChanged signal. 3537 3538 If the backend does not know how to handle the source it needs to 3539 change state to Phonon::ErrorState. Don't bother about handling KIO 3540 URLs. It is enough to handle AbstractMediaStream sources correctly. 3541 3542 \warning Keep the MediaSource object around as long as the backend 3543 uses the AbstractMediaStream returned by the MediaSource. In case 3544 that no other reference to the MediaSource exists and it is set to 3545 MediaSource::autoDelete, the AbstractMediaStream is deleted when the 3546 last MediaSource ref is deleted. 3547*/ 3548 3549/*! 3550 \fn virtual void Phonon::MediaObjectInterface::setNextSource(const MediaSource &source) = 0 3551 \internal 3552 3553 Sets the next source to be used for transitions. When a next source 3554 is set playback should continue with the new source. In that case 3555 finished and prefinishMarkReached are not emitted. 3556 3557 \param source The source to transition to (crossfade/gapless/gap). If 3558 \a source is an invalid MediaSource object then the queue is empty 3559 and the playback should stop normally. 3560 3561 \warning Keep the MediaSource object around as long as the backend 3562 uses the AbstractMediaStream returned by the MediaSource. In case 3563 that no other reference to the MediaSource exists and it is set to 3564 MediaSource::autoDelete, the AbstractMediaStream is deleted when the 3565 last MediaSource ref is deleted. 3566*/ 3567 3568/*! 3569 \class Phonon::EffectWidget effectwidget.h Phonon/EffectWidget 3570 \inmodule Phonon 3571 \inheaderfile Phonon/EffectWidget 3572 \since 4.4 3573 \brief The EffectWidget class provides a widget to control the parameters of an Effect. 3574 3575 The EffectWidget class provides a widget, with which an effects 3576 parameters can be controlled. The widget does not have an API, 3577 and is constructed with the \l{Phonon::}{Effect}, of which 3578 parameters should be controlled. 3579 3580 \snippet doc/src/snippets/audioeffects.cpp 1 3581 3582 The following image shows an example of an effect widget. 3583 3584 \image effectwidget.png 3585 3586 Note that some audio effects do not have parameters, and the 3587 widget will then not \l{QWidget::}{show()} at all. 3588 3589 \sa Effect, BackendCapabilities, EffectDescription, {Phonon Module} 3590*/ 3591 3592/*! 3593 \class Phonon::AbstractAudioOutput 3594 \inmodule Phonon 3595 \internal 3596 \brief Provides a common base class for all audio outputs. 3597 3598 \sa AudioOutput 3599*/ 3600 3601/*! 3602 \fn Phonon::AbstractAudioOutput::~AbstractAudioOutput() 3603 \internal 3604*/ 3605 3606/*! 3607 \class Phonon::AbstractAudioOutputPrivate 3608 \inmodule Phonon 3609 \since 4.4 3610 \internal 3611*/ 3612 3613/*! 3614 \class AudioOutputAdaptor 3615 \inmodule Phonon 3616 \brief Provides an adaptor class for interface org.kde.Phonon.AudioOutput 3617 \internal 3618*/ 3619 3620/*! 3621 \class Phonon::VolumeSlider 3622 \inmodule Phonon 3623 \inheaderfile Phonon/VolumeSlider 3624 \since 4.4 3625 \brief The VolumeSlider widget provides a slider that is used to control the volume of an audio output device. 3626 3627 The slider also displays an icon indicating if the volume of the 3628 \l{Phonon::}{AudioOutput} it is connected to is muted. The icon 3629 can be removed with setMuteVisible(). 3630 3631 It is possible to set the \l{maximumVolume}{maximum} value of the 3632 slider. By default, the minimum and maximum values of the slider 3633 are 0.0 (no sound) to 1.0 (the maximum volume the audio output can 3634 produce). 3635 3636 Here follows a code example: 3637 3638 \snippet doc/src/snippets/volumeslider.cpp 0 3639 3640 \omit mention how to change the style of the slider. \endomit 3641 3642 \sa {Phonon Module} 3643*/ 3644 3645/*! 3646 \property Phonon::VolumeSlider::maximumVolume 3647 3648 This property holds the maximum volume that can be set with this slider. 3649 3650 By default the maximum value is 1.0 (100%). 3651*/ 3652 3653/*! 3654 \property Phonon::VolumeSlider::orientation 3655 This property holds the orientation of the slider. 3656 3657 The orientation must be Qt::Vertical (the default) or Qt::Horizontal. 3658*/ 3659 3660/*! 3661 \property Phonon::VolumeSlider::tracking 3662 This property holds whether slider tracking is enabled. 3663 3664 If tracking is enabled (the default), the volume changes 3665 while the slider is being dragged. If tracking is 3666 disabled, the volume changes only when the user 3667 releases the slider. 3668*/ 3669 3670/*! 3671 \property Phonon::VolumeSlider::pageStep 3672 This property holds the page step. 3673 3674 The larger of two natural steps that a slider provides and 3675 typically corresponds to the user pressing PageUp or PageDown. 3676 3677 Defaults to 5 (5% of the voltage). 3678*/ 3679 3680/*! 3681 \property Phonon::VolumeSlider::singleStep 3682 This property holds the single step. 3683 3684 The smaller of two natural steps that a slider provides and 3685 typically corresponds to the user pressing an arrow key. 3686 3687 Defaults to 1 (1% of the voltage). 3688*/ 3689 3690/*! 3691 \property Phonon::VolumeSlider::muteVisible 3692 This property holds whether the mute button/icon next to the slider is visible. 3693 3694 By default the mute button/icon is visible. 3695*/ 3696 3697/*! 3698 \property Phonon::VolumeSlider::iconSize 3699 \brief the icon size used for the mute button/icon. 3700 3701 The default size is defined by the GUI style. 3702*/ 3703 3704/*! 3705 \fn explicit Phonon::VolumeSlider::VolumeSlider(QWidget *parent = 0) 3706 Constructs a new volume slider with the given \a parent. 3707*/ 3708 3709/*! 3710 \fn explicit Phonon::VolumeSlider::VolumeSlider(AudioOutput *output, QWidget *parent = 0) 3711 Constructs a new volume slider with the given \a output object and \a parent. 3712*/ 3713 3714/*! 3715 \fn Phonon::VolumeSlider::~VolumeSlider() 3716*/ 3717 3718/*! 3719 \fn AudioOutput *Phonon::VolumeSlider::audioOutput() const 3720*/ 3721 3722/*! 3723 \fn void Phonon::VolumeSlider::setAudioOutput(Phonon::AudioOutput *output) 3724 3725 Sets the audio output object to be controlled by this slider to the specified 3726 \a output object. 3727*/ 3728 3729/*! 3730 \class Phonon::VolumeSliderPrivate 3731 \inmodule Phonon 3732 \since 4.4 3733 \internal 3734*/ 3735 3736/*! 3737 \class Phonon::MediaController 3738 \inmodule Phonon 3739 \inheaderfile Phonon/MediaController 3740 \since 4.4 3741 \brief The MediaController class controls optional features of a media file/device. 3742 3743 Some media sources have content that the \l{Phonon::}{MediaObject} 3744 does not provide control over, for instance, chapters in a DVD 3745 file. The functionality the media controller offers is 3746 dependent on the type of media source that is played back. 3747 Commonly, the media controller allows you to: 3748 3749 \list 3750 \o Navigate between \bold chapters. 3751 \o Navigate between \bold titles. 3752 \o Select between \bold angles. 3753 \endlist 3754 3755 The \l{Phonon::MediaController::}{Feature} enum explains these 3756 terms in more detail, and their context in playback of CD and DVD. 3757 3758 The media controller keeps a \l{Phonon::}{MediaObject}, of which 3759 \l{Phonon::MediaObject::currentSource()}{media source} is played 3760 back. You can still call the media object's functions, e.g., 3761 \l{Phonon::MediaObject::}{stop()}; this is all handled correctly 3762 by the media controller. You have the option of letting the media 3763 controller play all titles of a source in sequence by setting the 3764 \l{autoplayTitles()}{autoplay titles} option. 3765 3766 To start a playback using a media object, you call 3767 \l{Phonon::MediaObject::}{play()} on the media object. To play a 3768 specific title, use setCurrentTitle() and then call 3769 \l{Phonon::MediaObject::}{play()}. 3770 3771 \warning The Phonon::MediaController class is not yet supported by 3772 Qt backends. 3773 3774 \sa {Phonon Module} 3775*/ 3776 3777/*! 3778 \fn int Phonon::MediaController::availableAudioChannels() const 3779 \internal 3780*/ 3781 3782/*! 3783 \fn void Phonon::MediaController::availableAudioChannelsChanged() 3784 \internal 3785*/ 3786 3787/*! 3788 \fn QList<SubtitleDescription> Phonon::MediaController::availableSubtitles() const 3789 \internal 3790*/ 3791 3792/*! 3793 \fn void Phonon::MediaController::availableSubtitlesChanged() 3794 \internal 3795*/ 3796 3797/*! 3798 \fn AudioChannelDescription Phonon::MediaController::currentAudioChannel() const 3799 \internal 3800*/ 3801 3802/*! 3803 \fn SubtitleDescription Phonon::MediaController::currentSubtitle() const 3804 \internal 3805*/ 3806 3807/*! 3808 \fn void Phonon::MediaController::setCurrentAudioChannel(const Phonon::AudioChannelDescription &stream) 3809 \internal 3810*/ 3811 3812/*! 3813 \fn void Phonon::MediaController::setCurrentSubtitle(const Phonon::SubtitleDescription &stream) 3814 \internal 3815*/ 3816 3817/*! 3818 \fn Phonon::BackendCapabilities::availableAudioCaptureDevices() 3819 \internal 3820*/ 3821 3822/*! 3823 \fn Phonon::BackendCapabilities::Notifier::availableAudioCaptureDevicesChanged() 3824 \internal 3825*/ 3826 3827/*! 3828 \enum Phonon::MediaController::Feature 3829 3830 The values of this enum are interpreted differently depending on 3831 the type of media source, e.g., DVD or CD. We give examples for 3832 these sources. 3833 3834 \value Angles In the VOB (DVD) format, it is possible to to give 3835 several video streams of the same scene, each of which displays 3836 the scene from a different angle. The DVD viewer can then change 3837 between these angles. 3838 3839 \value Chapters In the VOB format, chapters are points in a 3840 single video stream that can be played and seeked to 3841 separately. 3842 3843 \value Titles On a CD, a title is a separate sound track. On DVD, 3844 a title is a separate VOB file. 3845 3846*/ 3847 3848/*! 3849 \fn Phonon::MediaController::MediaController(MediaObject *parent) 3850 3851 Constructs a new MediaController with the media object (\a parent) 3852 to be used by the media controller. 3853 3854 \sa MediaObject, Feature 3855*/ 3856 3857/*! 3858 \fn Phonon::MediaController::~MediaController() 3859*/ 3860 3861/*! 3862 \fn Features Phonon::MediaController::supportedFeatures() const 3863*/ 3864 3865/*! 3866 \fn int Phonon::MediaController::availableAngles() const 3867 3868 Returns the available angles that is available for the current 3869 media source. 3870 3871 \sa Feature 3872*/ 3873 3874/*! 3875 \fn int Phonon::MediaController::currentAngle() const 3876 3877 Returns the angle that is currently used. 3878 3879 \sa Feature 3880*/ 3881 3882/*! 3883 \fn int Phonon::MediaController::availableChapters() const 3884 3885 Returns the number of chapters the current media source 3886 contains. 3887 3888 \sa Feature 3889*/ 3890 3891/*! 3892 \fn int Phonon::MediaController::currentChapter() const 3893 3894 Returns the chapter that is currently being played back. 3895 3896 \sa Feature 3897*/ 3898 3899/*! 3900 \fn int Phonon::MediaController::availableTitles() const 3901 3902 Returns the number of titles that the current media source 3903 contains. 3904 3905 \sa Feature 3906*/ 3907 3908/*! 3909 \fn int Phonon::MediaController::currentTitle() const 3910 3911 Returns the title that is currently played back. 3912 3913 The current title is 0 (the first) by default. 3914 3915 \sa Feature 3916*/ 3917 3918/*! 3919 \fn bool Phonon::MediaController::autoplayTitles() const 3920 3921 Returns true if titles will automatically be played when the media 3922 is played; otherwise returns false. 3923 3924 The media controller will play the titles of the media source in 3925 sequence when the media object's \l{Phonon::MediaObject::}{play()} 3926 function is called. If the autoplay option is disabled, the media 3927 object will play the 3928 \l{Phonon::}{MediaController::currentTitle()}{current title} and then 3929 finish the playback. 3930 3931 \sa setAutoplayTitles(), currentTitle() 3932*/ 3933 3934/*! 3935 \fn void Phonon::MediaController::setAutoplayTitles(bool enable) 3936 3937 Sets the titles to play automatically when the media is played if 3938 \a enable is true; otherwise disables this option. 3939 3940 The media controller will play the titles of the media source in 3941 sequence when the media object's \l{Phonon::MediaObject::}{play()} 3942 function is called. If the autoplay option is disabled, the media 3943 object will play the 3944 \l{Phonon::}{MediaController::currentTitle()}{current title} and then 3945 finish the playback. 3946 3947 \sa autoplayTitles(), currentTitle() 3948*/ 3949 3950/*! 3951 \fn void Phonon::MediaController::setCurrentAngle(int angleNumber) 3952 3953 Sets the current angle to the given \a angleNumber if the media 3954 file or device supports navigation by angle number. 3955 3956 \sa Feature 3957*/ 3958 3959/*! 3960 \fn void Phonon::MediaController::setCurrentChapter(int chapterNumber) 3961 3962 Sets the current chapter to the given \a chapterNumber if the media 3963 file or device supports navigation by chapter number. 3964 3965 \sa Feature 3966*/ 3967 3968/*! 3969 \fn void Phonon::MediaController::setCurrentTitle(int titleNumber) 3970 3971 Skips to the given title \a titleNumber. 3972 3973 If it was playing before the title change it will start playback on the new title if 3974 autoplayTitles is enabled. 3975 3976 \sa Feature 3977*/ 3978 3979/*! 3980 \fn void Phonon::MediaController::nextTitle() 3981 3982 Skips to the next title. 3983 3984 If it was playing before the title change it will start playback on the next title if 3985 autoplayTitles is enabled. 3986 3987 \sa Feature 3988*/ 3989 3990/*! 3991 \fn void Phonon::MediaController::previousTitle() 3992 3993 Skips to the previous title. 3994 3995 If it was playing before the title change it will start playback on the previous title if 3996 autoplayTitles is enabled. 3997 3998 \sa Feature 3999*/ 4000 4001/*! 4002 \fn void Phonon::MediaController::availableAnglesChanged(int availableAngles) 4003 4004 This signal is emitted whenever the number of available angles changes. 4005 The new number of available angles is given by \a availableAngles. 4006 4007 \sa Feature 4008*/ 4009 4010/*! 4011 \fn void Phonon::MediaController::angleChanged(int angleNumber) 4012 4013 This signal is emitted whenever the current angle changes. 4014 The new angle number is given by \a angleNumber. 4015 4016 \sa Feature 4017*/ 4018 4019/*! 4020 \fn void Phonon::MediaController::availableChaptersChanged(int availableChapters) 4021 4022 This signal is emitted whenever the number of available chapters changes. 4023 The new number of available chapters is given by \a availableChapters. 4024 4025 \sa Feature 4026*/ 4027 4028/*! 4029 \fn void Phonon::MediaController::chapterChanged(int chapterNumber) 4030 4031 This signal is emitted whenever the current chapter changes. 4032 The new chapter number is given by \a chapterNumber. 4033 4034 \sa Feature 4035*/ 4036 4037/*! 4038 \fn void Phonon::MediaController::availableTitlesChanged(int availableTitles) 4039 4040 This signal is emitted whenever the number of available titles changes. 4041 The new number of available titles is given by \a availableTitles. 4042 4043 \sa Feature 4044*/ 4045 4046/*! 4047 \fn void Phonon::MediaController::titleChanged(int titleNumber) 4048 4049 This signal is emitted whenever the current title changes. 4050 The new title number is given by \a titleNumber. 4051 4052 \sa Feature 4053*/ 4054 4055/*! 4056 \class Phonon::VideoWidget 4057 \inmodule Phonon 4058 \inheaderfile Phonon/VideoWidget 4059 \since 4.4 4060 \ingroup advanced 4061 \ingroup multimedia 4062 \brief The VideoWidget class provides a widget that is used to display video. 4063 4064 The VideoWidget class renders the video of a media stream on a 4065 QWidget. It is connected to the \l{Phonon::}{MediaObject}, of 4066 which video stream it should render. You connect the two objects 4067 using the Phonon::createPath() function. 4068 4069 The widget has some possibilities to manipulate the video 4070 stream. You can change the brightness(), hue(), saturation(), 4071 and contrast(). 4072 4073 Resizing of the video is handled automatically, but you can affect 4074 the way the video is resized with the aspectRatio and scaleMode 4075 properties. By default, the widget will use the aspect ratio of 4076 the video stream itself. 4077 4078 The video widget takes the size of the video when it receives a new video 4079 stream (i.e., when a new MediaSource is set on the MediaObject to which it is 4080 connected). If you need to know the size of the video, you can call 4081 \l{QWidget::}{sizeHint()} after the video has been loaded (i.e., after the 4082 MediaObject leaves the \l{Phonon::}{LoadingState}). 4083 4084 It is also possible to go to \l{fullScreen}{full screen} mode. 4085 4086 A typical example of usage follows below: 4087 4088 \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 21 4089 4090 \sa {Phonon Module} 4091*/ 4092 4093/*! 4094 \fn Phonon::VideoWidget::VideoWidget(QWidget *parent = 0) 4095 4096 Constructs a new video widget with the specified \a parent. 4097*/ 4098 4099/*! 4100 \fn Phonon::VideoWidget::VideoWidget(VideoWidgetPrivate &d, QWidget *parent) 4101 \internal 4102 4103 Constructs a new video widget with the specified \a parent. 4104*/ 4105 4106/*! 4107 \fn bool Phonon::VideoWidget::event(QEvent *) 4108 \reimp 4109*/ 4110 4111/*! 4112 \fn void Phonon::VideoWidget::mouseMoveEvent(QMouseEvent *) 4113 \reimp 4114*/ 4115 4116/*! 4117 \fn Phonon::VideoWidget::snapshot() const 4118 \since 4.7 4119 4120 Returns a snapshot of the current frame shown in the widget. 4121*/ 4122 4123/*! 4124 \enum Phonon::VideoWidget::ScaleMode 4125 4126 The ScaleMode enum describes how to treat aspect ratio during 4127 resizing of video. 4128 4129 \value FitInView The video will be fitted to fill the view 4130 keeping aspect ratio. 4131 \value ScaleAndCrop The video is scaled 4132*/ 4133 4134/*! 4135 \property Phonon::VideoWidget::fullScreen 4136 This property holds whether the video is shown using the complete 4137 screen. 4138 4139 The property differs from QWidget::fullScreen in that it is 4140 writeable. 4141 4142 By default the widget is not shown in fullScreen. 4143 4144 \warning When switching to full screen mode using setFullScreen(), 4145 the widget onto which the video is rendered is shown as a 4146 top-level window. Key event forwarding is handled by VideoWidget, 4147 but if you need to handle other events, e.g., mouse events, you 4148 should handle fullscreen mode yourself. 4149*/ 4150 4151/*! 4152 \property Phonon::VideoWidget::aspectRatio 4153 Defaults to AspectRatioAuto. 4154 4155 \sa AspectRatio 4156*/ 4157 4158/*! 4159 \property Phonon::VideoWidget::scaleMode 4160 4161 If the size of the widget and the size of the video are not equal. 4162 The video will be zoomed to fit the widget. The smaller zoom 4163 (AddBarsScaleMode) adds black bars at the left/right or top/bottom to 4164 make all of the image visible (default). The bigger zoom (ExpandMode) 4165 fills the widget completely, keeping all information in one direction 4166 and leaving parts of the image outside of the widget in the other 4167 direction. 4168*/ 4169 4170/*! 4171 \property Phonon::VideoWidget::brightness 4172 4173 This property holds brightness of the video. 4174 4175 Default is 0. Acceptable values are in range of -1, 1. 4176*/ 4177 4178/*! 4179 \property Phonon::VideoWidget::contrast 4180 4181 This property holds the contrast of the video. 4182 4183 Default is 0. Acceptable values are in range of -1, 1. 4184*/ 4185 4186/*! 4187 \property Phonon::VideoWidget::hue 4188 4189 This property holds the hue of the video. 4190 4191 Default is 0. Acceptable values are in range of -1, 1. 4192*/ 4193 4194/*! 4195 \property Phonon::VideoWidget::saturation 4196 4197 This property holds saturation of the video. 4198 4199 Default is 0. Acceptable values are in range of -1, 1. 4200*/ 4201 4202/*! 4203 \enum Phonon::VideoWidget::AspectRatio 4204 4205 Defines the width:height to be used for the video. 4206 4207 \value AspectRatioAuto 4208 Let the decoder find the aspect ratio automatically from the 4209 media file (this is the default). 4210 4211 \value AspectRatioWidget 4212 Fits the video into the widget making the aspect ratio depend 4213 solely on the size of the widget. This way the aspect ratio 4214 is freely resizeable by the user. 4215 4216 \value AspectRatio4_3 4217 Make width/height == 4/3, which is the old TV size and 4218 monitor size (1024/768 == 4/3). (4:3) 4219 4220 \value AspectRatio16_9 4221 Make width/height == 16/9, which is the size of most current 4222 media. (16:9) 4223*/ 4224 4225/*! 4226 \fn void Phonon::VideoWidget::exitFullScreen() 4227 4228 Convenience slot, calling setFullScreen(false) 4229*/ 4230 4231 4232/*! 4233 \fn void Phonon::VideoWidget::enterFullScreen() 4234 4235 Convenience slot, calling setFullScreen(true) 4236*/ 4237 4238/*! 4239 \class Phonon::VideoWidgetInterface 4240 \inmodule Phonon 4241 \since 4.4 4242 \internal 4243*/ 4244 4245/*! 4246 \fn virtual Phonon::VideoWidgetInterface::~VideoWidgetInterface() 4247*/ 4248 4249/*! 4250 \fn virtual Phonon::VideoWidget::AspectRatio Phonon::VideoWidgetInterface::aspectRatio() const = 0 4251 \internal 4252*/ 4253 4254/*! 4255 \fn virtual void Phonon::VideoWidgetInterface::setAspectRatio(Phonon::VideoWidget::AspectRatio ratio) = 0 4256 \internal 4257*/ 4258 4259/*! 4260 \fn virtual qreal Phonon::VideoWidgetInterface::brightness() const = 0 4261 \internal 4262*/ 4263 4264/*! 4265 \fn virtual void Phonon::VideoWidgetInterface::setBrightness(qreal) = 0 4266 \internal 4267*/ 4268 4269/*! 4270 \fn virtual Phonon::VideoWidget::ScaleMode Phonon::VideoWidgetInterface::scaleMode() const = 0 4271 \internal 4272*/ 4273 4274/*! 4275 \fn virtual void Phonon::VideoWidgetInterface::setScaleMode(Phonon::VideoWidget::ScaleMode mode) = 0 4276 \internal 4277*/ 4278 4279/*! 4280 \fn virtual qreal Phonon::VideoWidgetInterface::contrast() const = 0 4281 \internal 4282*/ 4283 4284/*! 4285 \fn virtual void Phonon::VideoWidgetInterface::setContrast(qreal) = 0 4286 \internal 4287*/ 4288 4289/*! 4290 \fn virtual qreal Phonon::VideoWidgetInterface::hue() const = 0 4291 \internal 4292*/ 4293 4294/*! 4295 \fn virtual void Phonon::VideoWidgetInterface::setHue(qreal) = 0 4296 \internal 4297*/ 4298 4299/*! 4300 \fn virtual qreal Phonon::VideoWidgetInterface::saturation() const = 0 4301 \internal 4302*/ 4303 4304/*! 4305 \fn virtual void Phonon::VideoWidgetInterface::setSaturation(qreal) = 0 4306 \internal 4307*/ 4308 4309/*! 4310 \fn virtual QWidget *Phonon::VideoWidgetInterface::widget() = 0 4311 \internal 4312*/ 4313 4314/*! 4315 \class Phonon::VideoWidgetInterface44 4316 \inmodule Phonon 4317 \since 4.7 4318*/ 4319 4320/*! 4321 \fn Phonon::VideoWidgetInterface44::snapshot() const 4322*/ 4323 4324/*! 4325 \typedef Phonon::VideoWidgetInterfaceLatest 4326 \inmodule Phonon 4327 \since 4.7 4328*/ 4329 4330/*! 4331 \class Phonon::PlatformPlugin 4332 \inmodule Phonon 4333 \since 4.4 4334 \internal 4335*/ 4336 4337/*! 4338 \fn virtual AbstractMediaStream *Phonon::PlatformPlugin::createMediaStream(const QUrl &url, QObject *parent) = 0 4339 4340 Creates a AbstractMediaStream object with the given \a parent that provides the data 4341 for the given URL specified by \a url. 4342 \omit 4343 On KDE this uses KIO. 4344 \endomit 4345*/ 4346 4347/*! 4348 \fn virtual QIcon Phonon::PlatformPlugin::icon(const QString &name) const = 0 4349 4350 Returns the icon for the given icon name. 4351*/ 4352 4353/*! 4354 \fn virtual void Phonon::PlatformPlugin::notification(const char *notificationName, const QString &text, 4355 const QStringList &actions, QObject *receiver, const char *actionSlot) const = 0 4356 4357 Shows a notification pop-up with the given \a notificationName and \a text. 4358 Each action in the associated list of \a actions is connected to the \a actionSlot 4359 of the specified \a receiver object, which is expected to act on the actions as 4360 they are triggered by the user. 4361*/ 4362 4363/*! 4364 \fn virtual QString Phonon::PlatformPlugin::applicationName() const = 0 4365 4366 Returns the name of the application. For most Qt application this is 4367 QCoreApplication::applicationName(), but for KDE this is overridden by KAboutData. 4368*/ 4369 4370 4371/*! 4372 \fn virtual QObject *Phonon::PlatformPlugin::createBackend() = 0 4373 4374 Creates a backend object. This way the platform can decide the backend preference. 4375*/ 4376 4377/*! 4378 \fn virtual QObject *Phonon::PlatformPlugin::createBackend(const QString &library, const QString &version) = 0 4379 4380 Using the library loader of the platform, loads a given backend provided the 4381 specified \a library and \a version. 4382*/ 4383 4384/*! 4385 \fn virtual bool Phonon::PlatformPlugin::isMimeTypeAvailable(const QString &mimeType) const = 0 4386 4387 Tries to check whether the default backend supports the MIME type specified by \a mimeType 4388 without loading the actual backend library. 4389 \omit 4390 On KDE this reads the MIME type list from the .desktop file of 4391 the backend. 4392 \endomit 4393*/ 4394 4395/*! 4396 \fn virtual void Phonon::PlatformPlugin::saveVolume(const QString &outputName, qreal volume) = 0 4397 4398 Saves the volume for the given output. 4399*/ 4400 4401/*! 4402 \fn virtual qreal Phonon::PlatformPlugin::loadVolume(const QString &outputName) const = 0 4403 4404 Loads the volume for the given output. 4405*/ 4406 4407/*! 4408 \class Phonon::MediaNode 4409 \inmodule Phonon 4410 \inheaderfile Phonon/MediaNode 4411 \since 4.4 4412 \brief The MediaNode class is the base class for all nodes in a media graph. 4413 4414 In all phonon applications, one builds a media graph consisting of 4415 MediaNodes. The graph will take multimedia content, e.g., from a 4416 file, as input. After its nodes have processed the multimedia, the 4417 graph will output the media again, e.g., to a sound card. 4418 4419 The multimedia content is streamed over \l{Phonon::}{Path}s 4420 between the nodes in the graph. You can query the paths that are 4421 connected to a media node with inputPaths() and outputPaths(). 4422 4423 You can check whether the node is implemented by the current 4424 backend by calling isValid(). This does not guarantee that an 4425 instance of the class works as expected, but that the backend has 4426 implemented functionality for the class. 4427 4428 Currently, Phonon has four media nodes: \l{Phonon::}{MediaObject}, 4429 \l{Phonon::}{AudioOutput}, \l{Phonon::}{VideoWidget}, and \l{Phonon::}{Effect}. 4430 Please refer to their class descriptions for details about their usage, and to 4431 find out which nodes can be connected to each other. See also \l{Building 4432 Graphs} in Phonon's \l{Phonon Overview}{overview} document. 4433 4434 Two nodes are connected to each other using the 4435 Phonon::createPath() or \l{Phonon::}{Path::insertEffect()} 4436 functions (only \l{Phonon::Effect}s use 4437 \l{Phonon::Path::}{insertEffect()}). We show a code example below, 4438 in which we build a media graph for video playback and then query 4439 its media nodes for their \l{Phonon::}{Path}s: 4440 4441 \snippet doc/src/snippets/medianodesnippet.cpp 0 4442 4443 When you create a Phonon application, you will likely build the 4444 graph yourself. This makes isValid() the most useful function of 4445 this class. The other two functions help navigate the graph, which 4446 you do not need to do as you created the nodes yourself. 4447 4448 \sa {Phonon Overview}, Phonon::MediaObject, 4449 Phonon::AudioOutput, Phonon::VideoWidget, {Phonon Module} 4450*/ 4451 4452/*! 4453 \fn virtual Phonon::MediaNode::~MediaNode() 4454 4455 Destroys the media node and any paths connecting it to other 4456 nodes. Any \l{Phonon::}{Effect}s connected to these paths will 4457 also be deleted. 4458*/ 4459 4460/*! 4461 \fn bool Phonon::MediaNode::isValid() const 4462 4463 Returns true if the backend provides an implementation of this 4464 class; otherwise returns false. 4465 4466 This does not guarantee that instances of the class works as 4467 expected, but that the backend has implemented the functionality 4468 for this class. For instance, Qt's GStreamer backend will return 4469 true for instances of the \l{Phonon::}{AudioOutput} class, even if 4470 there is a problem with GStreamer and it could not play sound. 4471 4472*/ 4473 4474/*! 4475 \fn QList<Path> Phonon::MediaNode::inputPaths() const 4476 4477 Returns the paths that inputs multimedia to this media node. 4478 4479 \sa outputPaths() 4480*/ 4481 4482/*! 4483 \fn QList<Path> Phonon::MediaNode::outputPaths() const 4484 4485 Returns the paths to which this media node outputs media. 4486 4487 \sa inputPaths() 4488*/ 4489 4490/*! 4491 \fn Phonon::MediaNode::MediaNode(MediaNodePrivate &dd) 4492 \internal 4493*/ 4494 4495/*! 4496 \class Phonon::GlobalConfig 4497 \inmodule Phonon 4498 \since 4.4 4499 \internal 4500*/ 4501 4502/*! 4503 \fn Phonon::GlobalConfig::GlobalConfig() 4504 \internal 4505*/ 4506 4507/*! 4508 \fn Phonon::GlobalConfig::~GlobalConfig() 4509 \internal 4510*/ 4511 4512/*! 4513 \fn QList<int> Phonon::GlobalConfig::audioOutputDeviceListFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const 4514 \internal 4515*/ 4516 4517/*! 4518 \fn int Phonon::GlobalConfig::audioOutputDeviceFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const 4519 \internal 4520*/ 4521 4522/*! 4523 \class Phonon::ObjectDescriptionData 4524 \inmodule Phonon 4525 \since 4.4 4526 \internal 4527 \brief Data class for objects describing devices or features of the backend. 4528 4529 \sa Phonon::BackendCapabilities 4530*/ 4531 4532/*! 4533 \fn bool Phonon::ObjectDescriptionData::operator==(const ObjectDescriptionData &otherDescription) const 4534 4535 Returns \c true if this ObjectDescription describes the same 4536 as \a otherDescription; otherwise returns \c false. 4537*/ 4538 4539/*! 4540 \fn QString Phonon::ObjectDescriptionData::name() const 4541 4542 Returns the name of the capture source. 4543 4544 \return A string that should be presented to the user to 4545 choose the capture source. 4546*/ 4547 4548/*! 4549 \fn QString Phonon::ObjectDescriptionData::description() const 4550 4551 Returns a description of the capture source. This text should 4552 make clear what sound source this is, which is sometimes hard 4553 to describe or understand from just the name. 4554 4555 \return A string describing the capture source. 4556*/ 4557 4558/*! 4559 \fn QVariant Phonon::ObjectDescriptionData::property(const char *name) const 4560 4561 Returns a named property. 4562 4563 If the property is not set an invalid value is returned. 4564 4565 \sa propertyNames() 4566*/ 4567 4568/*! 4569 \fn QList<QByteArray> Phonon::ObjectDescriptionData::propertyNames() const 4570 4571 Returns all names that return valid data when property() is called. 4572 4573 \sa property() 4574*/ 4575 4576/*! 4577 \fn bool Phonon::ObjectDescriptionData::isValid() const 4578 4579 Returns true if the Tuple is valid (index != -1); otherwise returns 4580 false. 4581*/ 4582 4583/*! 4584 \fn int Phonon::ObjectDescriptionData::index() const 4585 4586 A unique identifier for this device/. Used internally 4587 to distinguish between the devices/. 4588 4589 \return An integer that uniquely identifies every device. 4590*/ 4591 4592/*! 4593 \fn static ObjectDescriptionData *Phonon::ObjectDescriptionData::fromIndex(ObjectDescriptionType type, int index) 4594 \internal 4595*/ 4596 4597/*! 4598 \fn Phonon::ObjectDescriptionData::~ObjectDescriptionData() 4599 \internal 4600*/ 4601 4602/*! 4603 \fn Phonon::ObjectDescriptionData::ObjectDescriptionData(ObjectDescriptionPrivate * = 0) 4604 \internal 4605*/ 4606 4607/*! 4608 \class Phonon::AddonInterface 4609 \inmodule Phonon 4610 \since 4.4 4611 \internal 4612 \brief Interface for Menu, Chapter, Angle and Title/Track control. 4613*/ 4614 4615/*! 4616 \fn virtual Phonon::AddonInterface::~AddonInterface() 4617 \internal 4618*/ 4619 4620/*! 4621 \enum Phonon::AddonInterface::Interface 4622 4623 This enum describes the type of interface represented by an AddonInterface object. 4624 4625 \value NavigationInterface 4626 \value ChapterInterface 4627 \value AngleInterface 4628 \value TitleInterface 4629*/ 4630 4631/*! 4632 \enum Phonon::AddonInterface::NavigationCommand 4633 \internal 4634 \value Menu1Button 4635*/ 4636 4637/*! 4638 \enum Phonon::AddonInterface::ChapterCommand 4639 \internal 4640 \value availableChapters 4641 \value chapter 4642 \value setChapter 4643*/ 4644 4645/*! 4646 \enum Phonon::AddonInterface::AngleCommand 4647 \internal 4648 \value availableAngles 4649 \value angle 4650 \value setAngle 4651*/ 4652 4653/*! 4654 \enum Phonon::AddonInterface::TitleCommand 4655 \internal 4656 \value availableTitles 4657 \value title 4658 \value setTitle 4659 \value autoplayTitles 4660 \value setAutoplayTitles 4661*/ 4662 4663/*! 4664 \fn virtual bool Phonon::AddonInterface::hasInterface(Interface iface) const = 0 4665 \internal 4666*/ 4667 4668/*! 4669 \fn virtual QVariant Phonon::AddonInterface::interfaceCall(Interface iface, int command, 4670 const QList<QVariant> &arguments) = 0 4671 \internal 4672*/ 4673 4674/*! 4675 \class Phonon::MediaNodePrivate 4676 \inmodule Phonon 4677 \since 4.4 4678 \internal 4679*/ 4680 4681/*! 4682 \namespace Phonon::Factory 4683 \inmodule Phonon 4684 \internal 4685*/ 4686 4687/*! 4688 \fn Sender *Phonon::Factory::sender() 4689 4690 Returns a pointer to the object emitting the signals. 4691 4692 \sa Sender::backendChanged() 4693*/ 4694 4695/*! 4696 \fn QObject *Phonon::Factory::createMediaObject(QObject *parent = 0) 4697 4698 Create a new backend object for a MediaObject. 4699 4700 \return a pointer to the MediaObject the backend provides. 4701*/ 4702 4703/*! 4704 \fn QObject *Phonon::Factory::createEffect(int effectId, QObject *parent = 0) 4705 4706 Create a new backend object for a Effect. 4707 4708 \return a pointer to the Effect the backend provides. 4709*/ 4710 4711/*! 4712 \fn QObject *Phonon::Factory::createVolumeFaderEffect(QObject *parent = 0) 4713 4714 Create a new backend object for a VolumeFaderEffect. 4715 4716 \return a pointer to the VolumeFaderEffect the backend provides. 4717*/ 4718 4719/*! 4720 \fn QObject *Phonon::Factory::createAudioOutput(QObject *parent = 0) 4721 4722 Create a new backend object for a AudioOutput. 4723 4724 \return a pointer to the AudioOutput the backend provides. 4725*/ 4726 4727/*! 4728 \fn QObject *Phonon::Factory::createVideoWidget(QObject *parent = 0) 4729 4730 Create a new backend object for a VideoWidget. 4731 4732 \return a pointer to the VideoWidget the backend provides. 4733*/ 4734 4735/*! 4736 \fn QObject *Phonon::Factory::backend(bool createWhenNull = true) 4737 4738 \return a pointer to the backend interface. 4739*/ 4740 4741/*! 4742 \fn QString Phonon::Factory::identifier() 4743 4744 Unique identifier for the Backend. Can be used in configuration files 4745 for example. 4746*/ 4747 4748 4749/*! 4750 \fn QString Phonon::Factory::backendName() 4751 4752 Get the name of the Backend. 4753 \omit 4754 It's the name from the .desktop file. 4755 \endomit 4756*/ 4757 4758/*! 4759 \fn QString Phonon::Factory::backendComment() 4760 4761 Get the comment of the Backend. 4762 \omit 4763 It's the comment from the .desktop file. 4764 \endomit 4765*/ 4766 4767/*! 4768 \fn QString Phonon::Factory::backendVersion() 4769 4770 Get the version of the Backend. 4771 \omit 4772 It's the version from the .desktop file. 4773 \endomit 4774 4775 The version is especially interesting if there are several versions 4776 available for binary incompatible versions of the backend's media 4777 framework. 4778*/ 4779 4780/*! 4781 \fn QString Phonon::Factory::backendIcon() 4782 4783 Get the icon (name) of the Backend. 4784 \omit 4785 It's the icon from the .desktop file. 4786 \endomit 4787*/ 4788 4789/*! 4790 \fn QString Phonon::Factory::backendWebsite() 4791 4792 Get the website of the Backend. 4793 \omit 4794 It's the website from the .desktop file. 4795 \endomit 4796*/ 4797 4798/*! 4799 \fn QObject *Phonon::Factory::registerQObject(QObject *object) 4800 4801 Registers the given backend \a object with the factory. 4802*/ 4803 4804/*! 4805 \fn bool Phonon::Factory::isMimeTypeAvailable(const QString &mimeType) 4806*/ 4807 4808/*! 4809 \fn void Phonon::Factory::registerFrontendObject(MediaNodePrivate *) 4810 \internal 4811*/ 4812 4813/*! 4814 \fn void Phonon::Factory::deregisterFrontendObject(MediaNodePrivate *) 4815 \internal 4816*/ 4817 4818/*! 4819 \fn void Phonon::Factory::setBackend(QObject *) 4820*/ 4821 4822/*! 4823 \fn PlatformPlugin *Phonon::Factory::platformPlugin() 4824*/ 4825 4826/*! 4827/*! 4828 \class Phonon::AbstractMediaStreamPrivate 4829 \inmodule Phonon 4830 \since 4.4 4831 \internal 4832*/ 4833 4834/*! 4835 \class Phonon::FrontendInterfacePrivate 4836 \inmodule Phonon 4837 \since 4.4 4838 \internal 4839*/ 4840 4841/*! 4842 \class Phonon::EffectWidgetPrivate 4843 \inmodule Phonon 4844 \since 4.4 4845 \internal 4846*/ 4847 4848/*! 4849 \class Phonon::IODeviceStream 4850 \inmodule Phonon 4851 \since 4.4 4852 \internal 4853*/ 4854 4855/*! 4856 \fn explicit Phonon::IODeviceStream::IODeviceStream(QIODevice *ioDevice, QObject *parent = 0) 4857 \internal 4858 4859 Creates a new IODeviceStream with the given \a ioDevice and \a 4860 parent. 4861 4862*/ 4863 4864/*! 4865 \fn Phonon::IODeviceStream::~IODeviceStream() 4866 \internal 4867*/ 4868 4869/*! 4870 \fn void Phonon::IODeviceStream::reset() 4871 \internal 4872*/ 4873 4874/*! 4875 \fn void Phonon::IODeviceStream::needData() 4876 \internal 4877*/ 4878 4879/*! 4880 \fn void Phonon::IODeviceStream::seekStream(qint64) 4881 \internal 4882*/ 4883 4884/*! 4885 \namespace Phonon::Platform 4886 \inmodule Phonon 4887 \internal 4888*/ 4889 4890/*! 4891 \typedef Phonon::EffectDescriptionModel 4892 \inmodule Phonon 4893 \brief provides a item view model containing available audio effects. 4894 4895*/ 4896 4897/*! 4898 \typedef Phonon::SubtitleDescription 4899 \inmodule Phonon 4900 \internal 4901*/ 4902 4903/*! 4904 \typedef Phonon::SubtitleDescriptionModel 4905 \inmodule Phonon 4906 \internal 4907*/ 4908 4909/*! 4910 \typedef Phonon::AudioChannelDescription 4911 \inmodule Phonon 4912 \internal 4913*/ 4914 4915/*! 4916 \typedef Phonon::AudioChannelDescriptionModel 4917 \inmodule Phonon 4918 \internal 4919*/ 4920 4921/*! 4922 \typedef Phonon::AudioCaptureDevice 4923 \inmodule Phonon 4924 \internal 4925*/ 4926 4927/*! 4928 \typedef Phonon::AudioCaptureDeviceModel 4929 \inmodule Phonon 4930 \internal 4931*/ 4932 4933/*! 4934 \typedef Phonon::CleanUpFunction 4935 \inmodule Phonon 4936 \internal 4937*/ 4938 4939/*! 4940 \typedef Phonon::QObjectPair 4941 \inmodule Phonon 4942 \since 4.4 4943 \internal 4944 4945*/ 4946 4947/*! 4948 \typedef Phonon::AudioOutputDeviceModel 4949 \inmodule Phonon 4950 \brief provides an item view model containing available audio output devices. 4951 4952*/ 4953 4954/*! 4955 \fn uint Phonon::qHash(const Phonon::EffectParameter ¶m) 4956 \internal 4957 4958*/ 4959 4960/*! 4961 \fn Phonon::CleanUpGlobalStatic::~CleanUpGlobalStatic() 4962 \internal 4963*/ 4964 4965/*! 4966 \class Phonon::ConstIface 4967 \inmodule Phonon 4968 \since 4.4 4969 \internal 4970*/ 4971 4972/*! 4973 \class Phonon::CleanUpGlobalStatic 4974 \inmodule Phonon 4975 \since 4.4 4976 \internal 4977*/ 4978 4979/*! 4980 \class Phonon::EffectParameterPrivate 4981 \inmodule Phonon 4982 \since 4.4 4983 \internal 4984 4985*/ 4986 4987/*! 4988 \class Phonon::QSettingsGroup 4989 \inmodule Phonon 4990 \since 4.4 4991 \internal 4992 4993*/ 4994 4995/*! 4996 \class Phonon::MediaNodeDestructionHandler 4997 \inmodule Phonon 4998 \since 4.4 4999 \internal 5000 5001*/ 5002 5003/*! 5004 \fn Phonon::MediaNodeDestructionHandler::~MediaNodeDestructionHandler() 5005 \internal 5006 Called from Base::~Base if this object was registered 5007 using BasePrivate::addDestructionHandler(). 5008*/ 5009 5010/*! 5011 \fn Phonon::MediaNodeDestructionHandler::phononObjectDestroyed(MediaNodePrivate *) 5012 \internal 5013*/ 5014 5015/*! 5016 \fn explicit Phonon::EffectWidget::EffectWidget(Effect *effect, QWidget *parent = 0) 5017 \internal 5018 5019 Constructs a new EffectWidget for the specified \a effect and with 5020 the specified \a parent. 5021*/ 5022 5023/*! 5024 \fn Phonon::EffectWidget::~EffectWidget() 5025 \internal 5026*/ 5027 5028/*! 5029 \fn QDebug Phonon::operator<<(QDebug s, const ObjectDescription<T> &o) 5030 \internal 5031*/ 5032 5033/*! 5034 \class Phonon::ListModelHelper 5035 \inmodule Phonon 5036 \since 4.4 5037 \internal 5038*/ 5039 5040/*! 5041 \class AudioOutputInterface42 5042 \inmodule Phonon 5043 \since 4.4 5044 \internal 5045*/ 5046 5047/*! 5048 \class Phonon::PulseSupport 5049 \inmodule Phonon 5050 \since 4.7 5051 \internal 5052*/ 5053 5054/*! 5055 \class Phonon::AudioDataOutput 5056 \inmodule Phonon 5057 \since 4.7 5058 5059 \brief The AudioDataOutput class provides access to audio data. 5060 5061 This class is used to obtain audio data, typically for the purpose of 5062 visualizing it. 5063 5064 Although it is not designed for realtime performance, the latencies 5065 associated with accessing the data should be low enough for applications 5066 that provide visualizations of the data. This class can also be used to 5067 save the audio data for further processing. 5068*/ 5069 5070/*! 5071 \enum Phonon::AudioDataOutput::Channel 5072 5073 This enum describes the channel audio data belongs to. 5074 5075 \value LeftChannel 5076 \value RightChannel 5077 \value CenterChannel 5078 \value LeftSurroundChannel 5079 \value RightSurroundChannel 5080 \value SubwooferChannel 5081*/ 5082 5083/*! 5084 \property Phonon::AudioDataOutput::dataSize 5085 \brief the number of samples passed via the dataReady() signal. 5086*/ 5087 5088/*! 5089 \fn int Phonon::AudioDataOutput::sampleRate() const 5090 5091 Returns the sample rate measured in Hertz, as reported by the backend. 5092 If the backend is unavailable -1 is returned. 5093*/ 5094 5095/*! 5096 \fn void Phonon::AudioDataOutput::endOfMedia(int remainingSamples) 5097 5098 This signal is emitted before the final dataReady() signal is emitted for 5099 a media. The \a remainingSamples value sent by the signal contains the 5100 number of samples that will be sent in the final dataReady() signal for 5101 the media. 5102*/ 5103 5104/*! 5105 \fn Phonon::AudioDataOutput::dataReady(const QMap<Phonon::AudioDataOutput::Channel, QVector<qint16> > &data) 5106 5107 This signal is emitted whenever there is data available to read. The 5108 \a data sent by the signal is supplied in the form of a map that holds the 5109 data for different output channels. 5110*/ 5111 5112/*! 5113 \fn Phonon::AudioDataOutputPrivate::AudioDataOutputPrivate() 5114 \internal 5115*/ 5116 5117/*! 5118 \fn Phonon::AudioDataOutputInterface::~AudioDataOutputInterface() 5119 5120 Destroys the data interface. 5121*/ 5122 5123/*! 5124 \fn Phonon::AudioDataOutputInterface::frontendObject() const 5125 \internal 5126*/ 5127 5128/*! 5129 \fn Phonon::AudioDataOutputInterface::setFrontendObject(AudioDataOutput *) 5130 \internal 5131*/ 5132 5133/*! 5134 \class Phonon::GlobalConfigPrivate 5135 \inmodule Phonon 5136 \internal 5137*/ 5138 5139/*! 5140 \class Phonon::AudioDataOutputPrivate 5141 \inmodule Phonon 5142 \internal 5143*/ 5144 5145/*! 5146 \class Phonon::AudioDataOutputInterface 5147 \inmodule Phonon 5148 \internal 5149*/ 5150 5151/*! 5152 \class Phonon::SwiftSlider 5153 \inmodule Phonon 5154 \internal 5155*/ 5156 5157/*! 5158 \fn Phonon::GlobalConfigPrivate::GlobalConfigPrivate() 5159 \internal 5160*/ 5161 5162/*! 5163 \fn Phonon::GlobalConfigPrivate::~GlobalConfigPrivate() 5164 \internal 5165*/ 5166 5167/*! 5168 \fn Phonon::SwiftSlider::~SwiftSlider() 5169 \internal 5170*/ 5171