2 * This file is part of DisOrder
3 * Copyright (C) 2005-2008 Richard Kettlewell
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
18 /** @file server/speaker.h
19 * @brief Speaker process
24 #ifdef WORDS_BIGENDIAN
25 # define MACHINE_AO_FMT AO_FMT_BIG
27 # define MACHINE_AO_FMT AO_FMT_LITTLE
30 /** @brief Minimum number of frames to try to play at once
32 * The main loop will only attempt to play any audio when this many
33 * frames are available (or the current track has reached the end).
34 * The actual number of frames it attempts to play will often be
35 * larger than this (up to three times).
37 * For ALSA we request a buffer of three times this size and set the low
38 * watermark to this amount. The goal is then to keep between 1 and 3 times
39 * this many frames in play.
41 * For other we attempt to play up to three times this many frames per
42 * shot. In practice we will often only send much less than this.
46 /** @brief Bytes to send per network packet
48 * This is the maximum number of bytes we pass to write(2); to determine actual
49 * packet sizes, add a UDP header and an IP header (and a link layer header if
50 * it's the link layer size you care about).
52 * Don't make this too big or arithmetic will start to overflow.
54 #define NETWORK_BYTES (1500-8/*UDP*/-40/*IP*/-8/*conservatism*/)
56 /** @brief Maximum number of FDs to poll for */
59 /** @brief Track structure
61 * Known tracks are kept in a linked list. Usually there will be at most two
62 * of these but rearranging the queue can cause there to be more.
65 /** @brief Next track */
68 /** @brief Input file descriptor */
69 int fd
; /* input FD */
71 /** @brief Track ID */
74 /** @brief Start position of data in buffer */
77 /** @brief Number of bytes of data in buffer */
80 /** @brief Set @c fd is at EOF */
83 /** @brief Total number of frames played */
84 unsigned long long played
;
86 /** @brief Slot in @ref fds */
89 /** @brief Set when playable
91 * A track becomes playable whenever it fills its buffer or reaches EOF; it
92 * stops being playable when it entirely empties its buffer. Tracks start
93 * out life not playable.
97 /** @brief Input buffer
99 * 1Mbyte is enough for nearly 6s of 44100Hz 16-bit stereo
101 char buffer
[1048576];
104 /** @brief Structure of a backend */
105 struct speaker_backend
{
106 /** @brief Which backend this is
108 * @c -1 terminates the list.
114 * This field is currently not used and must be 0.
118 /** @brief Initialization
120 * Called once at startup. This is responsible for one-time setup
121 * operations, for instance opening a network socket to transmit to.
123 * When writing to a native sound API this might @b not imply opening the
124 * native sound device - that might be done by @c activate below.
128 /** @brief Activation
129 * @return 0 on success, non-0 on error
131 * Called to activate the output device.
133 * On input @ref device_state may be anything. If it is @ref
134 * device_open then the device is already open but might be using
135 * the wrong sample format. The device should be reconfigured to
136 * use the right sample format.
138 * If it is @ref device_error then a retry is underway and an
139 * attempt to recover or re-open the device (with the right sample
140 * format) should be made.
142 * If it is @ref device_closed then the device should be opened with
143 * the right sample format.
145 * Some devices are effectively always open and have no error state, in which
146 * case this callback can be NULL. Note that @ref device_state still
147 * switches between @ref device_open and @ref device_closed in this case.
149 void (*activate
)(void);
151 /** @brief Play sound
152 * @param frames Number of frames to play
153 * @return Number of frames actually played
155 * If an error occurs (and it is not immediately recovered) this
156 * should set @ref device_state to @ref device_error.
158 size_t (*play
)(size_t frames
);
160 /** @brief Deactivation
162 * Called to deactivate the sound device. This is the inverse of @c
165 * For sound devices that are open all the time and have no error
166 * state, this callback can be NULL. Note that @ref device_state
167 * still switches between @ref device_open and @ref device_closed in
170 void (*deactivate
)(void);
172 /** @brief Called before poll()
173 * @param timeoutp Pointer to timeout
175 * Called before the call to poll().
177 * If desirable, should call addfd() to update the FD array and stash the
178 * slot number somewhere safe. This will only be called if @ref device_state
179 * is @ref device_open.
181 * @p timeoutp points to the poll timeout value in milliseconds. It may be
182 * reduced, but never increased.
184 * NB you can NOT assume that @c beforepoll is always called before @c play.
186 void (*beforepoll
)(int *timeoutp
);
188 /** @brief Called after poll()
189 * @return 1 if output device ready for play, 0 otherwise
191 * Called after the call to poll(). This will only be called if
192 * @ref device_state = @ref device_open.
194 * The return value should be 1 if the device was ready to play, or
200 /** @brief Possible device states */
202 /** @brief The device is closed */
205 /** @brief The device is open and ready to receive sound
207 * The current device sample format is potentially part of this state.
211 /** @brief An error has occurred on the device
213 * This state is used to ensure that a small interval is left
214 * between retrying the device. If errors just set @ref
215 * device_closed then the main loop would busy-wait on broken output
218 * The current device sample format is potentially part of this state.
223 extern enum device_states device_state
;
224 extern struct track
*tracks
;
225 extern struct track
*playing
;
227 extern const struct speaker_backend network_backend
;
228 extern const struct speaker_backend alsa_backend
;
229 extern const struct speaker_backend command_backend
;
230 extern const struct speaker_backend coreaudio_backend
;
231 extern const struct speaker_backend oss_backend
;
233 extern struct pollfd fds
[NFDS
];
238 int addfd(int fd
, int events
);
241 #endif /* SPEAKER_H */