Phonon

audiooutputinterface.h
1/*
2 Copyright (C) 2015-2016 Harald Sitter <sitter@kde.org>
3 Copyright (C) 2007-2008 Matthias Kretz <kretz@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) version 3, or any
9 later version accepted by the membership of KDE e.V. (or its
10 successor approved by the membership of KDE e.V.), Nokia Corporation
11 (or its successors, if any) and the KDE Free Qt Foundation, which shall
12 act as a proxy defined in Section 6 of version 3 of the license.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Lesser General Public License for more details.
18
19 You should have received a copy of the GNU Lesser General Public
20 License along with this library. If not, see <http://www.gnu.org/licenses/>.
21
22*/
23
24#ifndef PHONON_AUDIOOUTPUTINTERFACE_H
25#define PHONON_AUDIOOUTPUTINTERFACE_H
26
27#include "phononnamespace.h"
28#include "objectdescription.h"
29#include "phonondefs.h"
30#include <QtGlobal>
31
32namespace Phonon
33{
34/** \class AudioOutputInterface audiooutputinterface.h phonon/AudioOutputInterface
35 * \short Interface for AudioOutput objects
36 *
37 * The implementation can make use of the signals
38 * \code
39 void volumeChanged(qreal newVolume);
40 void audioDeviceFailed();
41 * \endcode
42 * to notify the frontend whenever the volume has changed or when an audioDeviceFailed (e.g. USB
43 * unplug or sound server failure).
44 *
45 * \author Matthias Kretz <kretz@kde.org>
46 */
47class AudioOutputInterface40
48{
49 public:
50 virtual ~AudioOutputInterface40() {}
51
52 /**
53 * Returns the current software volume.
54 *
55 * A value of 0.0 means muted, 1.0 means unchanged, 2.0 means double voltage (i.e. all
56 * samples are multiplied by 2).
57 */
58 virtual qreal volume() const = 0;
59 /**
60 * Sets the new current software volume.
61 *
62 * A value of 0.0 means muted, 1.0 means unchanged, 2.0 means double voltage (i.e. all
63 * samples are multiplied by 2).
64 *
65 * Every time the volume in the backend changes it should emit volumeChanged(qreal), also
66 * inside this function.
67 */
68 virtual void setVolume(qreal) = 0;
69
70 /**
71 * Returns the index of the device that is used. The index is the number returned from
72 * BackendInterface::objectDescriptionIndexes(AudioOutputDeviceType).
73 */
74 virtual int outputDevice() const = 0;
75 /**
76 * \deprecated
77 *
78 * Requests to change the current output device to the one identified by the passed index.
79 *
80 * The index is the number returned from
81 * BackendInterface::objectDescriptionIndexes(AudioOutputDeviceType).
82 *
83 * \returns \c true if the requested device works and is used after this call.
84 * \returns \c false if something failed and the device is not used after this call.
85 */
86 virtual bool setOutputDevice(int) = 0;
87};
88
89class AudioOutputInterface42 : public AudioOutputInterface40
90{
91 public:
92 /**
93 * Requests to change the current output device.
94 *
95 * \returns \c true if the requested device works and is used after this call.
96 * \returns \c false if something failed and the device is not used after this call.
97 */
98 virtual bool setOutputDevice(const Phonon::AudioOutputDevice &) = 0;
99
100 using AudioOutputInterface40::setOutputDevice;
101
102 /**
103 * Helper function for backends to get a list of (driver, handle) pairs for
104 * AudioOutputDevice objects that are listed by the platform plugin.
105 *
106 * Example:
107 * \code
108 typedef QPair<QByteArray, QString> PhononDeviceAccess;
109 const QList<PhononDeviceAccess> &deviceAccessList = deviceAccessListFor(deviceDesc);
110 foreach (const PhononDeviceAccess &access, deviceAccessList) {
111 const QByteArray &driver = access.first;
112 const QString &handle = access.second;
113 if (openDevice(driver, handle)) {
114 // we found the first pair in the list that works. done.
115 return;
116 }
117 // continue trying the other (driver, handle) pairs
118 }
119 // none of the (driver, handle) pairs worked, that means the whole AudioOutputDevice is
120 // inaccessible and the frontend needs to know (either by emitting audioDeviceFailed or
121 // returning false when called from setOutputDevice)
122 * \endcode
123 *
124 * At the time of this writing the following driver strings are known to be in use:
125 * \li \c alsa: The handle is the string to pass to snd_pcm_open (e.g. "dmix:CARD=0,DEV=1")
126 * \li \c oss: The handle is the device file (e.g. "/dev/dsp")
127 * \li \c pulseaudio: The handle contains the server string and the sink/source name
128 * separated by a newline character.
129 * (e.g. unix:/tmp/pulse-mkretz/native\nalsa_output.pci_8086_293e_sound_card_0_alsa_playback_0)
130 */
131 PHONON_EXPORT QList<QPair<QByteArray, QString> > deviceAccessListFor(const Phonon::AudioOutputDevice &) const;
132};
133
134class AudioOutputInterface47 : public AudioOutputInterface42
135{
136public:
137 /**
138 * This function is meant to be used in conjunction with PulseSupport
139 * to either get the property set for the associated PulseAudio straem or
140 * to automatically apply them to the environment.
141 *
142 * If a backend subsystem supports actively setting arbitrary properties
143 * this method should be preferred and PulseSupport::streamProperties()
144 * should be used.
145 * If a backend subsystem does not support setting arbitrary properties
146 * PulseSupport::setupStreamEnvironment() should be called as close to
147 * stream creation as possible to manipulate the process environment
148 * such that PulseAudio will pick up the properties.
149 *
150 * \param uuid the UUID used by PulseSupport to identify the associated stream
151 *
152 * \since 4.7.0
153 */
154 virtual void setStreamUuid(QString uuid) = 0;
155};
156
157class AudioOutputInterface49 : public AudioOutputInterface47
158{
159public:
160 /**
161 * Mutes the output.
162 *
163 * \param mute \c true if it is supposed to get muted \c false if not
164 *
165 * \since 4.9.0
166 */
167 virtual void setMuted(bool mute) = 0;
168
169 /**
170 * SIGNAL emitted when the muteness of the output changes.
171 *
172 * \warning When implementing the 4.9 interface this signal MUST be emitted
173 * from all relevant sources.
174 *
175 * This signal must be emitted whenever muteness is reached.
176 * The signal must only be emitted if setMuted was called, reaching mutness
177 * through other means (such as volume==0.0) does not count as muteness.
178 *
179 * \param mute \c true when the output is mute, \c false if it is not mute
180 *
181 * \since 4.9.0
182 */
183 virtual void mutedChanged(bool mute) = 0;
184};
185
186class AudioOutputInterface410 : public AudioOutputInterface49
187{
188public:
189 /**
190 * Forwards the output category to the backend after construction.
191 * The category is immutable so this is only called once, it is also never
192 * read from the backend (hence the lack of a getter) as the backend gets
193 * no choice in this matter.
194 * @param category the category that was set on the output.
195 */
196 virtual void setCategory(Phonon::Category category) = 0;
197};
198
199} // namespace Phonon
200
201#ifdef PHONON_BACKEND_VERSION_4_10
202namespace Phonon { typedef AudioOutputInterface410 AudioOutputInterface; }
203Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org")
204Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org")
205Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org")
206Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org")
207Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "6AudioOutputInterface.phonon.kde.org")
208#elif defined PHONON_BACKEND_VERSION_4_9
209namespace Phonon { typedef AudioOutputInterface49 AudioOutputInterface; }
210Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org")
211Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org")
212Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org")
213Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "5AudioOutputInterface.phonon.kde.org")
214Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org")
215#elif defined PHONON_BACKEND_VERSION_4_7
216namespace Phonon { typedef AudioOutputInterface47 AudioOutputInterface; }
217Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org")
218Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org")
219Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "4AudioOutputInterface.phonon.kde.org")
220Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org")
221Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org")
222#elif defined PHONON_BACKEND_VERSION_4_2
223namespace Phonon { typedef AudioOutputInterface42 AudioOutputInterface; }
224Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org")
225Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "3AudioOutputInterface.phonon.kde.org")
226Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org")
227Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org")
228Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org")
229#else
230namespace Phonon { typedef AudioOutputInterface40 AudioOutputInterface; }
231Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "AudioOutputInterface2.phonon.kde.org")
232Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org")
233Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org")
234Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org")
235Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org")
236#endif
237
238
239#endif // PHONON_AUDIOOUTPUTINTERFACE_H
AudioOutputInterface
Interface for AudioOutput objects.
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri Jan 24 2025 11:49:05 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.