Refactor loading sound resource as GIO stream
[projects/chimara/chimara.git] / libchimara / schannel.c
index f4c7bd63a43bdc7f62b1d3826e170f5f07fa4ab5..b30e1707096e7a213d132c1097e6ff42969ed046 100644 (file)
@@ -2,9 +2,9 @@
 #include <glib.h>
 #include <glib/gi18n-lib.h>
 #include <libchimara/glk.h>
-#ifdef GSTREAMER_SOUND
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
 #include <gst/gst.h>
-#endif
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 #include "magic.h"
 #include "schannel.h"
 #include "chimara-glk-private.h"
 
 #define VOLUME_TIMER_RESOLUTION 1.0 /* In milliseconds */
 
-extern GPrivate *glk_data_key;
+#ifdef GSTREAMER_0_10_SOUND
+#define OGG_MIMETYPE "application/ogg"
+#endif
+#ifdef GSTREAMER_1_0_SOUND
+#define OGG_MIMETYPE "audio/ogg"
+#endif
 
-#ifdef GSTREAMER_SOUND
+extern GPrivate glk_data_key;
+
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
 /* Stop any currently playing sound on this channel, and remove any
  format-specific GStreamer elements from the channel. */
 static void
@@ -25,6 +32,11 @@ clean_up_after_playing_sound(schanid_t chan)
 {
        if(!gst_element_set_state(chan->pipeline, GST_STATE_NULL))
                WARNING_S(_("Could not set GstElement state to"), "NULL");
+       if(chan->source)
+       {
+               gst_bin_remove(GST_BIN(chan->pipeline), chan->source);
+               chan->source = NULL;
+       }
        if(chan->demux)
        {
                gst_bin_remove(GST_BIN(chan->pipeline), chan->demux);
@@ -116,7 +128,7 @@ static void
 on_type_found(GstElement *typefind, guint probability, GstCaps *caps, schanid_t s)
 {
        gchar *type = gst_caps_to_string(caps);
-       if(strcmp(type, "application/ogg") == 0) {
+       if(strcmp(type, OGG_MIMETYPE) == 0) {
                s->demux = gst_element_factory_make("oggdemux", NULL);
                s->decode = gst_element_factory_make("vorbisdec", NULL);
                if(!s->demux || !s->decode) {
@@ -158,10 +170,53 @@ on_type_found(GstElement *typefind, guint probability, GstCaps *caps, schanid_t
                WARNING_S(_("Unexpected audio type in blorb"), type);
        }
 
+       /* This is necessary in case this handler occurs in the middle of a state
+       change */
+       gst_element_sync_state_with_parent(s->decode);
+       if(s->demux != NULL)
+               gst_element_sync_state_with_parent(s->demux);
+
 finally:
        g_free(type);
 }
-#endif /* GSTREAMER_SOUND */
+
+/* Load a sound resource into a GInputStream, by whatever method */
+static GInputStream *
+load_resource_into_giostream(glui32 snd)
+{
+       ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
+       GInputStream *retval;
+
+       if(glk_data->resource_map == NULL) {
+               if(glk_data->resource_load_callback == NULL) {
+                       WARNING(_("No resource map has been loaded yet."));
+                       return NULL;
+               }
+               char *filename = glk_data->resource_load_callback(CHIMARA_RESOURCE_SOUND, snd, glk_data->resource_load_callback_data);
+               if(filename == NULL) {
+                       WARNING(_("Error loading resource from alternative location."));
+                       return NULL;
+               }
+
+               GError *err = NULL;
+               GFile *file = g_file_new_for_path(filename);
+               retval = G_INPUT_STREAM(g_file_read(file, NULL, &err));
+               if(retval == NULL)
+                       IO_WARNING(_("Error loading resource from file"), filename, err->message);
+               g_free(filename);
+               g_object_unref(file);
+       } else {
+               giblorb_result_t resource;
+               giblorb_err_t result = giblorb_load_resource(glk_data->resource_map, giblorb_method_Memory, &resource, giblorb_ID_Snd, snd);
+               if(result != giblorb_err_None) {
+                       WARNING_S( _("Error loading resource"), giblorb_get_error_message(result) );
+                       return NULL;
+               }
+               retval = g_memory_input_stream_new_from_data(resource.data.ptr, resource.length, NULL);
+       }
+       return retval;
+}
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 
 /**
  * glk_schannel_create:
@@ -172,6 +227,23 @@ finally:
  * Remember that it is possible that the library will be unable to create a new
  * channel, in which case glk_schannel_create() will return %NULL.
  *
+ * When you create a channel using glk_schannel_create(), it has full volume,
+ * represented by the value 0x10000. Half volume would be 0x8000, three-quarters
+ * volume would be 0xC000, and so on. A volume of zero represents silence.
+ *
+ * You can overdrive the volume of a channel by setting a volume greater than 
+ * 0x10000. However, this is not recommended; the library may be unable to 
+ * increase the volume past full, or the sound may become distorted. You should 
+ * always create sound resources with the maximum volume you will need, and then
+ * reduce the volume when appropriate using the channel-volume calls.
+ *
+ * <note><para>
+ *   Mathematically, these volume changes should be taken as linear
+ *   multiplication of a waveform represented as linear samples. As I
+ *   understand it, linear PCM encodes the sound pressure, and therefore a
+ *   volume of 0x8000 should represent a 6 dB drop.
+ * </para></note>
+ *
  * Returns: A new sound channel, or %NULL.
  */
 schanid_t 
@@ -185,18 +257,21 @@ glk_schannel_create(glui32 rock)
  * @rock: The rock value to give the new sound channel.
  * @volume: Integer representing the volume; 0x10000 is 100&percnt;.
  *
- * [DRAFT SPEC]
- *
  * The glk_schannel_create_ext() call lets you create a channel with the volume
  * already set at a given level.
  *
+ * Not all libraries support glk_schannel_create_ext(). You should test the
+ * %gestalt_Sound2 selector before you rely on it; see <link
+ * linkend="chimara-Testing-for-Sound-Capabilities">Testing for Sound
+ * Capabilities</link>.
+ *
  * Returns: A new sound channel, or %NULL.
  */
 schanid_t
 glk_schannel_create_ext(glui32 rock, glui32 volume)
 {
-#ifdef GSTREAMER_SOUND
-       ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
+       ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
 
        schanid_t s = g_new0(struct glk_schannel_struct, 1);
        s->magic = MAGIC_SCHANNEL;
@@ -223,12 +298,11 @@ glk_schannel_create_ext(glui32 rock, glui32 volume)
        gst_object_unref(bus);
 
        /* Create GStreamer elements to put in the pipeline */
-       s->source = gst_element_factory_make("giostreamsrc", NULL);
        s->typefind = gst_element_factory_make("typefind", NULL);
        s->convert = gst_element_factory_make("audioconvert", NULL);
        s->filter = gst_element_factory_make("volume", NULL);
        s->sink = gst_element_factory_make("autoaudiosink", NULL);
-       if(!s->source || !s->typefind || !s->convert || !s->filter || !s->sink) {
+       if(!s->typefind || !s->convert || !s->filter || !s->sink) {
                WARNING(_("Could not create one or more GStreamer elements"));
                goto fail;
        }
@@ -238,9 +312,10 @@ glk_schannel_create_ext(glui32 rock, glui32 volume)
 
        /* Put the elements in the pipeline and link as many together as we can
         without knowing the type of the audio stream */
-       gst_bin_add_many(GST_BIN(s->pipeline), s->source, s->typefind, s->convert, s->filter, s->sink, NULL);
-       /* Link elements: Source -> typefinder -> ??? -> Converter -> Volume filter -> Sink */
-       if(!gst_element_link(s->source, s->typefind) || !gst_element_link_many(s->convert, s->filter, s->sink, NULL)) {
+       gst_bin_add_many(GST_BIN(s->pipeline), s->typefind, s->convert, s->filter, s->sink, NULL);
+
+       /* Link elements: ??? -> Converter -> Volume filter -> Sink */
+       if(!gst_element_link_many(s->convert, s->filter, s->sink, NULL)) {
                WARNING(_("Could not link GStreamer elements"));
                goto fail;
        }
@@ -253,7 +328,7 @@ fail:
        return NULL;
 #else
        return NULL;
-#endif /* GSTREAMER_SOUND */
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 }
 
 /**
@@ -268,8 +343,8 @@ glk_schannel_destroy(schanid_t chan)
 {
        VALID_SCHANNEL(chan, return);
 
-#ifdef GSTREAMER_SOUND
-       ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
+       ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
 
        if(!gst_element_set_state(chan->pipeline, GST_STATE_NULL))
                WARNING_S(_("Could not set GstElement state to"), "NULL");
@@ -288,7 +363,7 @@ glk_schannel_destroy(schanid_t chan)
        
        chan->magic = MAGIC_FREE;
        g_free(chan);
-#endif
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 }
 
 /**
@@ -310,8 +385,8 @@ glk_schannel_iterate(schanid_t chan, glui32 *rockptr)
 {
        VALID_SCHANNEL_OR_NULL(chan, return NULL);
 
-#ifdef GSTREAMER_SOUND
-       ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
+       ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
        GList *retnode;
        
        if(chan == NULL)
@@ -327,7 +402,7 @@ glk_schannel_iterate(schanid_t chan, glui32 *rockptr)
        return retval;
 #else
        return NULL;
-#endif /* GSTREAMER_SOUND */
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 }
 
 /**
@@ -402,9 +477,14 @@ glk_schannel_play(schanid_t chan, glui32 snd)
  * sound is playing, there will be no notification event.
  *
  * Not all libraries support sound notification. You should test the
- * %gestalt_SoundNotify selector before you rely on it; see <link
+ * %gestalt_Sound2 selector before you rely on it; see <link
  * linkend="chimara-Testing-for-Sound-Capabilities">Testing for Sound 
  * Capabilities</link>.
+ *
+ * Note that you can play a sound on a channel whose volume is zero. This has
+ * no audible result, unless you later change the volume; but it produces
+ * notifications as usual. You can also play a sound on a paused channel; the
+ * sound is paused immediately, and does not progress.
  * 
  * Returns: 1 on success, 0 on failure.
  */
@@ -412,10 +492,7 @@ glui32
 glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
 {
        VALID_SCHANNEL(chan, return 0);
-#ifdef GSTREAMER_SOUND
-       ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
-       GInputStream *stream;
-
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
        /* Stop the previous sound */
        clean_up_after_playing_sound(chan);
 
@@ -425,54 +502,34 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
                return 1;
        }
 
-       /* Load the sound into a GInputStream, by whatever method */
-       if(!glk_data->resource_map) {
-               if(!glk_data->resource_load_callback) {
-                       WARNING(_("No resource map has been loaded yet."));
-                       return 0;
-               }
-               gchar *filename = glk_data->resource_load_callback(CHIMARA_RESOURCE_SOUND, snd, glk_data->resource_load_callback_data);
-               if(!filename) {
-                       WARNING(_("Error loading resource from alternative location."));
-                       return 0;
-               }
+       GInputStream *stream = load_resource_into_giostream(snd);
+       if(stream == NULL)
+               return 0;
 
-               GError *err = NULL;
-               GFile *file = g_file_new_for_path(filename);
-               stream = G_INPUT_STREAM(g_file_read(file, NULL, &err));
-               if(!stream) {
-                       IO_WARNING(_("Error loading resource from file"), filename, err->message);
-                       g_free(filename);
-                       g_object_unref(file);
-                       return 0;
-               }
-               g_free(filename);
-               g_object_unref(file);
-       } else {
-               giblorb_result_t resource;
-               giblorb_err_t result = giblorb_load_resource(glk_data->resource_map, giblorb_method_Memory, &resource, giblorb_ID_Snd, snd);
-               if(result != giblorb_err_None) {
-                       WARNING_S( _("Error loading resource"), giblorb_get_error_message(result) );
-                       return 0;
-               }
-               stream = g_memory_input_stream_new_from_data(resource.data.ptr, resource.length, NULL);
+       chan->source = gst_element_factory_make("giostreamsrc", NULL);
+       g_object_set(chan->source, "stream", stream, NULL);
+       g_object_unref(stream); /* Now owned by GStreamer element */
+       gst_bin_add(GST_BIN(chan->pipeline), chan->source);
+       if(!gst_element_link(chan->source, chan->typefind)) {
+               WARNING(_("Could not link GStreamer elements"));
+               clean_up_after_playing_sound(chan);
+               return 0;
        }
 
        chan->repeats = repeats;
        chan->resource = snd;
        chan->notify = notify;
-       g_object_set(chan->source, "stream", stream, NULL);
-       g_object_unref(stream); /* Now owned by GStreamer element */
        
        /* Play the sound; unless the channel is paused, then pause it instead */
        if(!gst_element_set_state(chan->pipeline, chan->paused? GST_STATE_PAUSED : GST_STATE_PLAYING)) {
                WARNING_S(_("Could not set GstElement state to"), chan->paused? "PAUSED" : "PLAYING");
+               clean_up_after_playing_sound(chan);
                return 0;
        }
        return 1;
 #else
        return 0;
-#endif
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 }
 
 /**
@@ -482,8 +539,6 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
  * @sndarray: Array of sound resource numbers.
  * @soundcount: Length of @sndarray, must be equal to @chanarray.
  * @notify: If nonzero, request a notification when each sound finishes.
- * 
- * [DRAFT SPEC]
  *
  * This works the same as glk_schannel_play_ext(), except that you can specify
  * more than one sound. The channel references and sound resource numbers are
@@ -496,6 +551,11 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
  * a number from 0 to @soundcount.)
  *
  * <note><para>
+ *   If the @notify argument is nonzero, you will get a separate sound
+ *   notification event as each sound finishes. They will all have the same
+ *   @val2 value.
+ * </para></note>
+ * <note><para>
  *   Note that you have to supply @chancount and @soundcount as separate
  *   arguments, even though they are required to be the same. This is an awkward
  *   consequence of the way array arguments are dispatched in Glulx.
@@ -514,10 +574,8 @@ glk_schannel_play_multi(schanid_t *chanarray, glui32 chancount, glui32 *sndarray
        for(count = 0; count < chancount; count++)
                VALID_SCHANNEL(chanarray[count], return 0);
 
-#ifdef GSTREAMER_SOUND
-       ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
-       GInputStream *stream;
-
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
+       ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
        if(!glk_data->resource_map && !glk_data->resource_load_callback) {
                WARNING(_("No resource map has been loaded yet."));
                return 0;
@@ -531,43 +589,24 @@ glk_schannel_play_multi(schanid_t *chanarray, glui32 chancount, glui32 *sndarray
                /* Stop the previous sound */
                clean_up_after_playing_sound(chanarray[count]);
 
-               /* Load the sound into a GInputStream, by whatever method */
-               if(!glk_data->resource_map) {
-                       gchar *filename = glk_data->resource_load_callback(CHIMARA_RESOURCE_SOUND, sndarray[count], glk_data->resource_load_callback_data);
-                       if(!filename) {
-                               WARNING(_("Error loading resource from alternative location."));
-                               skiparray[count] = TRUE;
-                               continue;
-                       }
+               GInputStream *stream = load_resource_into_giostream(sndarray[count]);
+               if(stream == NULL) {
+                       skiparray[count] = TRUE;
+                       continue;
+               }
 
-                       GError *err = NULL;
-                       GFile *file = g_file_new_for_path(filename);
-                       stream = G_INPUT_STREAM(g_file_read(file, NULL, &err));
-                       if(!stream) {
-                               IO_WARNING(_("Error loading resource from file"), filename, err->message);
-                               g_free(filename);
-                               g_object_unref(file);
-                               skiparray[count] = TRUE;
-                               continue;
-                       }
-                       g_free(filename);
-                       g_object_unref(file);
-               } else {
-                       giblorb_result_t resource;
-                       giblorb_err_t result = giblorb_load_resource(glk_data->resource_map, giblorb_method_Memory, &resource, giblorb_ID_Snd, sndarray[count]);
-                       if(result != giblorb_err_None) {
-                               WARNING_S( _("Error loading resource"), giblorb_get_error_message(result) );
-                               skiparray[count] = TRUE;
-                               continue;
-                       }
-                       stream = g_memory_input_stream_new_from_data(resource.data.ptr, resource.length, NULL);
+               chanarray[count]->source = gst_element_factory_make("giostreamsrc", NULL);
+               g_object_set(chanarray[count]->source, "stream", stream, NULL);
+               g_object_unref(stream); /* Now owned by GStreamer element */
+               gst_bin_add(GST_BIN(chanarray[count]->pipeline), chanarray[count]->source);
+               if(!gst_element_link(chanarray[count]->source, chanarray[count]->typefind)) {
+                       WARNING(_("Could not link GStreamer elements"));
+                       clean_up_after_playing_sound(chanarray[count]);
                }
 
                chanarray[count]->repeats = 1;
                chanarray[count]->resource = sndarray[count];
                chanarray[count]->notify = notify;
-               g_object_set(chanarray[count]->source, "stream", stream, NULL);
-               g_object_unref(stream); /* Now owned by GStreamer element */
        }
 
        /* Start all the sounds as close to each other as possible. */
@@ -580,6 +619,7 @@ glk_schannel_play_multi(schanid_t *chanarray, glui32 chancount, glui32 *sndarray
                if(!gst_element_set_state(chanarray[count]->pipeline, chanarray[count]->paused? GST_STATE_PAUSED : GST_STATE_PLAYING)) {
                        WARNING_S(_("Could not set GstElement state to"), chanarray[count]->paused? "PAUSED" : "PLAYING");
                        skiparray[count] = TRUE;
+                       clean_up_after_playing_sound(chanarray[count]);
                        continue;
                }
                successes++;
@@ -588,7 +628,7 @@ glk_schannel_play_multi(schanid_t *chanarray, glui32 chancount, glui32 *sndarray
        return successes;
 #else
        return 0;
-#endif
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 }
 
 /**
@@ -602,7 +642,7 @@ void
 glk_schannel_stop(schanid_t chan)
 {
        VALID_SCHANNEL(chan, return);
-#ifdef GSTREAMER_SOUND
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
        clean_up_after_playing_sound(chan);
 #endif
 }
@@ -610,9 +650,7 @@ glk_schannel_stop(schanid_t chan)
 /**
  * glk_schannel_pause:
  * @chan: Channel to pause.
- * 
- * [DRAFT SPEC]
- * 
+ *
  * Pause any sound playing in the channel. This does not generate any
  * notification events. If the channel is already paused, this does nothing.
  * 
@@ -632,6 +670,7 @@ glk_schannel_pause(schanid_t chan)
        /* Mark the channel as paused even if there is no sound playing yet */
        chan->paused = TRUE;
 
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
        GstState state;
        if(gst_element_get_state(chan->pipeline, &state, NULL, GST_CLOCK_TIME_NONE) != GST_STATE_CHANGE_SUCCESS) {
                WARNING(_("Could not get GstElement state"));
@@ -644,16 +683,22 @@ glk_schannel_pause(schanid_t chan)
                WARNING_S(_("Could not set GstElement state to"), "PAUSED");
                return;
        }
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 }
 
 /**
  * glk_schannel_unpause:
  * @chan: Channel to unpause.
- * 
- * [DRAFT SPEC]
  *
  * Unpause the channel. Any paused sounds begin playing where they left off. If
  * the channel is not already paused, this does nothing.
+ *
+ * <note><para>
+ *   This means, for example, that you can pause a channel that is currently
+ *   not playing any sounds. If you then add a sound to the channel, it will
+ *   not start playing; it will be paused at its beginning. If you later
+ *   unpaise the channel, the sound will commence.
+ * </para></note>
  */
 void
 glk_schannel_unpause(schanid_t chan)
@@ -666,6 +711,7 @@ glk_schannel_unpause(schanid_t chan)
        /* Mark the channel as not paused in any case */
        chan->paused = FALSE;
 
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
        GstState state;
        if(gst_element_get_state(chan->pipeline, &state, NULL, GST_CLOCK_TIME_NONE) != GST_STATE_CHANGE_SUCCESS) {
                WARNING(_("Could not get GstElement state"));
@@ -678,21 +724,7 @@ glk_schannel_unpause(schanid_t chan)
                WARNING_S(_("Could not set GstElement state to"), "PLAYING");
                return;
        }
-}
-
-static double
-volume_glk_to_gstreamer(glui32 volume_glk)
-{
-       return CLAMP(((double)volume_glk / 0x10000), 0.0, 10.0);
-}
-
-static void
-channel_set_volume_immediately(schanid_t chan, double volume, glui32 notify)
-{
-       g_object_set(chan->filter, "volume", volume, NULL);
-
-       if(notify != 0)
-               event_throw(chan->glk, evtype_VolumeNotify, NULL, 0, notify);
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 }
 
 /**
@@ -700,19 +732,20 @@ channel_set_volume_immediately(schanid_t chan, double volume, glui32 notify)
  * @chan: Channel to set the volume of.
  * @vol: Integer representing the volume; 0x10000 is 100&percnt;.
  *
- * Sets the volume in the channel. When you create a channel, it has full 
- * volume, represented by the value 0x10000. Half volume would be 0x8000, 
- * three-quarters volume would be 0xC000, and so on. A volume of zero represents
- * silence, although the sound is still considered to be playing.
+ * Sets the volume in the channel, from 0 (silence) to 0x10000 (full volume).
+ * Again, you can overdrive the volume by setting a value greater than 0x10000,
+ * but this is not recommended.
+ *
+ * The glk_schannel_set_volume() function does not include duration and notify
+ * values. Both are assumed to be zero: immediate change, no notification.
  *
- * You can call this function between sounds, or while a sound is playing. The 
- * effect is immediate.
+ * You can call this function between sounds, or while a sound is playing.
+ * However, a zero-duration change while a sound is playing may produce
+ * unpleasant clicks.
  * 
- * You can overdrive the volume of a channel by setting a volume greater than 
- * 0x10000. However, this is not recommended; the library may be unable to 
- * increase the volume past full, or the sound may become distorted. You should 
- * always create sound resources with the maximum volume you will need, and then
- * call glk_schannel_set_volume() to reduce the volume when appropriate.
+ * At most one volume change can be occurring on a sound channel at any time.
+ * If you call this function while a previous volume change is in progress, the
+ * previous change is interrupted.
  *
  * Not all libraries support this function. You should test the
  * %gestalt_SoundVolume selector before you rely on it; see <link
@@ -727,15 +760,16 @@ channel_set_volume_immediately(schanid_t chan, double volume, glui32 notify)
 void 
 glk_schannel_set_volume(schanid_t chan, glui32 vol)
 {
-       VALID_SCHANNEL(chan, return);
-       /* Silently ignore out-of-range volume values */
+       glk_schannel_set_volume_ext(chan, vol, 0, 0);
+}
 
-#ifdef GSTREAMER_SOUND
-       double volume = volume_glk_to_gstreamer(vol);
-       channel_set_volume_immediately(chan, volume, 0);
-#endif
+static double
+volume_glk_to_gstreamer(glui32 volume_glk)
+{
+       return CLAMP(((double)volume_glk / 0x10000), 0.0, 10.0);
 }
 
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
 static gboolean
 volume_change_timeout(schanid_t chan)
 {
@@ -749,6 +783,7 @@ volume_change_timeout(schanid_t chan)
                if(chan->volume_notify)
                        event_throw(chan->glk, evtype_VolumeNotify, NULL, 0, chan->volume_notify);
 
+               chan->volume_timer_id = 0;
                return FALSE;
        }
 
@@ -765,6 +800,7 @@ volume_change_timeout(schanid_t chan)
 
        return TRUE;
 }
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 
 /**
  * glk_schannel_set_volume_ext:
@@ -772,9 +808,7 @@ volume_change_timeout(schanid_t chan)
  * @vol: Integer representing the volume; 0x10000 is 100&percnt;.
  * @duration: Length of volume change in milliseconds, or 0 for immediate.
  * @notify: If nonzero, requests a notification when the volume change finishes.
- * 
- * [DRAFT SPEC]
- * 
+ *
  * Sets the volume in the channel, from 0 (silence) to 0x10000 (full volume).
  * Again, you can overdrive the volume by setting a value greater than 0x10000,
  * but this is not recommended.
@@ -787,18 +821,15 @@ volume_change_timeout(schanid_t chan)
  * event with type #evtype_VolumeNotify. The window will be %NULL, @val1 will be
  * zero, and @val2 will be the nonzero value you passed as @notify.
  *
- * The glk_schannel_set_volume() does not include @duration and @notify values.
- * Both are assumed to be zero: immediate change, no notification.
- *
- * You can call these functions between sounds, or while a sound is playing.
+ * You can call this function between sounds, or while a sound is playing.
  * However, a zero-duration change while a sound is playing may produce
  * unpleasant clicks.
  *
  * At most one volume change can be occurring on a sound channel at any time. If
- * you call one of these functions while a previous volume change is in
- * progress, the previous change is interrupted. The beginning point of the new
- * volume change should be wherever the previous volume change was interrupted
- * (rather than the previous change's beginning or ending point).
+ * you call this function while a previous volume change is in progress, the
+ * previous change is interrupted. The beginning point of the new volume change
+ * should be wherever the previous volume change was interrupted (rather than
+ * the previous change's beginning or ending point).
  *
  * Not all libraries support these functions. You should test the appropriate
  * gestalt selectors before you rely on them; see "Testing for Sound
@@ -809,12 +840,20 @@ glk_schannel_set_volume_ext(schanid_t chan, glui32 vol, glui32 duration, glui32
 {
        VALID_SCHANNEL(chan, return);
        /* Silently ignore out-of-range volume values */
+
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
+       /* Interrupt a previous volume change */
+       if(chan->volume_timer_id > 0)
+               g_source_remove(chan->volume_timer_id);
        
-#ifdef GSTREAMER_SOUND
        double target_volume = volume_glk_to_gstreamer(vol);
 
        if(duration == 0) {
-               channel_set_volume_immediately(chan, target_volume, notify);
+               g_object_set(chan->filter, "volume", target_volume, NULL);
+
+               if(notify != 0)
+                       event_throw(chan->glk, evtype_VolumeNotify, NULL, 0, notify);
+
                return;
        }
 
@@ -828,8 +867,8 @@ glk_schannel_set_volume_ext(schanid_t chan, glui32 vol, glui32 duration, glui32
        chan->volume_notify = notify;
 
        /* Set up a timer for the volume */
-       g_timeout_add(VOLUME_TIMER_RESOLUTION, (GSourceFunc)volume_change_timeout, chan);
-#endif
+       chan->volume_timer_id = g_timeout_add(VOLUME_TIMER_RESOLUTION, (GSourceFunc)volume_change_timeout, chan);
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 }
 
 /**
@@ -848,8 +887,8 @@ glk_schannel_set_volume_ext(schanid_t chan, glui32 vol, glui32 duration, glui32
 void 
 glk_sound_load_hint(glui32 snd, glui32 flag)
 {
-#ifdef GSTREAMER_SOUND
-       ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
+#if defined(GSTREAMER_0_10_SOUND) || defined(GSTREAMER_1_0_SOUND)
+       ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
        giblorb_result_t resource;
        giblorb_err_t result;
 
@@ -880,5 +919,5 @@ glk_sound_load_hint(glui32 snd, glui32 flag)
                        return;
                }
        }
-#endif /* GSTREAMER_SOUND */
+#endif /* GSTREAMER_0_10_SOUND || GSTREAMER_1_0_SOUND */
 }