2 * This file is part of DisOrder
3 * Copyright (C) 2005, 2006, 2007 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 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * 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, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
20 /** @file server/speaker.h
21 * @brief Speaker process
26 #ifdef WORDS_BIGENDIAN
27 # define MACHINE_AO_FMT AO_FMT_BIG
29 # define MACHINE_AO_FMT AO_FMT_LITTLE
32 /** @brief How many seconds of input to buffer
34 * While any given connection has this much audio buffered, no more reads will
35 * be issued for that connection. The decoder will have to wait.
37 #define BUFFER_SECONDS 5
39 /** @brief Minimum number of frames to try to play at once
41 * The main loop will only attempt to play any audio when this many
42 * frames are available (or the current track has reached the end).
43 * The actual number of frames it attempts to play will often be
44 * larger than this (up to three times).
46 * For ALSA we request a buffer of three times this size and set the low
47 * watermark to this amount. The goal is then to keep between 1 and 3 times
48 * this many frames in play.
50 * For other we attempt to play up to three times this many frames per
51 * shot. In practice we will often only send much less than this.
55 /** @brief Bytes to send per network packet
57 * Don't make this too big or arithmetic will start to overflow.
59 #define NETWORK_BYTES (1024+sizeof(struct rtp_header))
61 /** @brief Maximum RTP playahead (ms) */
62 #define RTP_AHEAD_MS 1000
64 /** @brief Maximum number of FDs to poll for */
67 /** @brief Track structure
69 * Known tracks are kept in a linked list. Usually there will be at most two
70 * of these but rearranging the queue can cause there to be more.
73 struct track *next; /* next track */
74 int fd; /* input FD */
76 size_t start, used; /* start + bytes used */
77 int eof; /* input is at EOF */
78 int got_format; /* got format yet? */
79 ao_sample_format format; /* sample format */
80 unsigned long long played; /* number of frames played */
81 char *buffer; /* sample buffer */
82 size_t size; /* sample buffer size */
83 int slot; /* poll array slot */
86 /** @brief Structure of a backend */
87 struct speaker_backend {
88 /** @brief Which backend this is
90 * @c -1 terminates the list.
100 /** @brief Lock to configured sample format */
101 #define FIXED_FORMAT 0x0001
103 /** @brief Initialization
105 * Called once at startup. This is responsible for one-time setup
106 * operations, for instance opening a network socket to transmit to.
108 * When writing to a native sound API this might @b not imply opening the
109 * native sound device - that might be done by @c activate below.
113 /** @brief Activation
114 * @return 0 on success, non-0 on error
116 * Called to activate the output device.
118 * On input @ref device_state may be anything. If it is @ref
119 * device_open then the device is already open but might be using
120 * the wrong sample format. The device should be reconfigured to
121 * use the right sample format.
123 * If it is @ref device_error then a retry is underway and an
124 * attempt to recover or re-open the device (with the right sample
125 * format) should be made.
127 * If it is @ref device_closed then the device should be opened with
128 * the right sample format.
130 * If the @ref FIXED_FORMAT flag is not set then @ref device_format
131 * must be set on success.
133 * Some devices are effectively always open and have no error state,
134 * in which case this callback can be NULL. In this case @ref
135 * FIXED_FORMAT must be set. Note that @ref device_state still
136 * switches between @ref device_open and @ref device_closd in this
139 void (*activate)(void);
141 /** @brief Play sound
142 * @param frames Number of frames to play
143 * @return Number of frames actually played
145 * If an error occurs (and it is not immediately recovered) this
146 * should set @ref device_state to @ref device_error.
148 size_t (*play)(size_t frames);
150 /** @brief Deactivation
152 * Called to deactivate the sound device. This is the inverse of @c
155 * For sound devices that are open all the time and have no error
156 * state, this callback can be NULL. Note that @ref device_state
157 * still switches between @ref device_open and @ref device_closd in
160 void (*deactivate)(void);
162 /** @brief Called before poll()
164 * Called before the call to poll(). Should call addfd() to update
165 * the FD array and stash the slot number somewhere safe. This will
166 * only be called if @ref device_state = @ref device_open.
168 void (*beforepoll)(void);
170 /** @brief Called after poll()
171 * @return 1 if output device ready for play, 0 otherwise
173 * Called after the call to poll(). This will only be called if
174 * @ref device_state = @ref device_open.
176 * The return value should be 1 if the device was ready to play, or
182 /** @brief Possible device states */
184 /** @brief The device is closed */
187 /** @brief The device is open and ready to receive sound
189 * The current device sample format is potentially part of this state.
193 /** @brief An error has occurred on the device
195 * This state is used to ensure that a small interval is left
196 * between retrying the device. If errors just set @ref
197 * device_closed then the main loop would busy-wait on broken output
200 * The current device sample format is potentially part of this state.
205 extern enum device_states device_state;
206 extern ao_sample_format device_format;
207 extern struct track *tracks;
208 extern struct track *playing;
210 #endif /* SPEAKER_H */