1 module pulse.scache; 2 3 version(linux): 4 5 import pulse.context; 6 import pulse.stream; 7 import pulse.context; 8 import pulse.proplist; 9 import pulse.channelmap; 10 import pulse.sample; 11 import pulse.operation; 12 import pulse.volume; 13 14 extern (C): 15 16 /*** 17 This file is part of PulseAudio. 18 19 Copyright 2004-2006 Lennart Poettering 20 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB 21 22 PulseAudio is free software; you can redistribute it and/or modify 23 it under the terms of the GNU Lesser General Public License as published 24 by the Free Software Foundation; either version 2.1 of the License, 25 or (at your option) any later version. 26 27 PulseAudio is distributed in the hope that it will be useful, but 28 WITHOUT ANY WARRANTY; without even the implied warranty of 29 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 30 General Public License for more details. 31 32 You should have received a copy of the GNU Lesser General Public License 33 along with PulseAudio; if not, see <http://www.gnu.org/licenses/>. 34 ***/ 35 36 /** \page scache Sample Cache 37 * 38 * \section overv_sec Overview 39 * 40 * The sample cache provides a simple way of overcoming high network latencies 41 * and reducing bandwidth. Instead of streaming a sound precisely when it 42 * should be played, it is stored on the server and only the command to start 43 * playing it needs to be sent. 44 * 45 * \section create_sec Creation 46 * 47 * To create a sample, the normal stream API is used (see \ref streams). The 48 * function pa_stream_connect_upload() will make sure the stream is stored as 49 * a sample on the server. 50 * 51 * To complete the upload, pa_stream_finish_upload() is called and the sample 52 * will receive the same name as the stream. If the upload should be aborted, 53 * simply call pa_stream_disconnect(). 54 * 55 * \section play_sec Playing samples 56 * 57 * To play back a sample, simply call pa_context_play_sample(): 58 * 59 * \code 60 * pa_operation *o; 61 * 62 * o = pa_context_play_sample(my_context, 63 * "sample2", // Name of my sample 64 * NULL, // Use default sink 65 * PA_VOLUME_NORM, // Full volume 66 * NULL, // Don't need a callback 67 * NULL 68 * ); 69 * if (o) 70 * pa_operation_unref(o); 71 * \endcode 72 * 73 * \section rem_sec Removing samples 74 * 75 * When a sample is no longer needed, it should be removed on the server to 76 * save resources. The sample is deleted using pa_context_remove_sample(). 77 */ 78 79 /** \file 80 * All sample cache related routines 81 * 82 * See also \subpage scache 83 */ 84 85 /** Callback prototype for pa_context_play_sample_with_proplist(). The 86 * idx value is the index of the sink input object, or 87 * PA_INVALID_INDEX on failure. \since 0.9.11 */ 88 alias pa_context_play_sample_cb_t = void function (pa_context* c, uint idx, void* userdata); 89 90 /** Make this stream a sample upload stream. Returns zero on success. */ 91 int pa_stream_connect_upload (pa_stream* s, size_t length); 92 93 /** Finish the sample upload, the stream name will become the sample 94 * name. You cancel a sample upload by issuing 95 * pa_stream_disconnect(). Returns zero on success. */ 96 int pa_stream_finish_upload (pa_stream* s); 97 98 /** Remove a sample from the sample cache. Returns an operation object which 99 * may be used to cancel the operation while it is running. */ 100 pa_operation* pa_context_remove_sample (pa_context* c, const(char)* name, pa_context_success_cb_t cb, void* userdata); 101 102 /** Play a sample from the sample cache to the specified device. If 103 * the latter is NULL use the default sink. Returns an operation 104 * object */ 105 106 /**< Context */ 107 /**< Name of the sample to play */ 108 /**< Sink to play this sample on */ 109 /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea. */ 110 /**< Call this function after successfully starting playback, or NULL */ 111 /**< Userdata to pass to the callback */ 112 pa_operation* pa_context_play_sample ( 113 pa_context* c, 114 const(char)* name, 115 const(char)* dev, 116 pa_volume_t volume, 117 pa_context_success_cb_t cb, 118 void* userdata); 119 120 /** Play a sample from the sample cache to the specified device, 121 * allowing specification of a property list for the playback 122 * stream. If the latter is NULL use the default sink. Returns an 123 * operation object. \since 0.9.11 */ 124 125 /**< Context */ 126 /**< Name of the sample to play */ 127 /**< Sink to play this sample on */ 128 /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea. */ 129 /**< Property list for this sound. The property list of the cached entry will have this merged into it. */ 130 /**< Call this function after successfully starting playback, or NULL */ 131 /**< Userdata to pass to the callback */ 132 pa_operation* pa_context_play_sample_with_proplist ( 133 pa_context* c, 134 const(char)* name, 135 const(char)* dev, 136 pa_volume_t volume, 137 const(pa_proplist)* proplist, 138 pa_context_play_sample_cb_t cb, 139 void* userdata); 140