Previous: Audio Devices, Up: Media

53.4 Media Threads

Media threads can be thought of a way to plug a certain media stream into a certain output device. Since SXEmacs merely supports audio output devices the only partition which is finally “played” is an audio substream.

The current structure looks like: 

                          up          up
               +------------> Stream <------------+
               |                 ^                |
         first |                 | up             | last
               v       next      |        next    v
         substream1 <-----> substream2 <-----> substream3
                    prev               prev

Similarly for Threads: 

                          up          up
               +------------> Thread <------------+
               |                 ^                |
         first |                 | up             | last
               v       next      |        next    v
         subthread1 <-----> subthread2 <-----> subthread3
                    prev               prev

To be precise, threads are the containers for the streams. Streams are stored (along with devices) inside threads, while substreams are stored inside subthreads. In source/sink language, a thread is the cable to plug a source (stream) to a sink (device).

This brings us to: 

                          up  +========+  up
                      ,-----> | Thread | <-----,
                     /        +--------+        \
                    /         | Stream |         \
                   /          | Device |          \
                  /           | State  |           \
                 /            | PState |            \
                /             | Result |             \
               /              +========+              \
               |                   ^                  |
         first |                   | up               | last
               v                   |                  v
        +==========+    next +==========+    next +==========+
        |subthread1| <-----> |subthread2| <-----> |subthread3|
        +----------+ prev    +----------+ prev    +----------+
        |substream1|         |substream2|         |substream3|
        |pthread_t1|         |pthread_t2|         |pthread_t3|
        |privdata1 |         |privdata2 |         |privdata3 |
        +==========+         +==========+         +==========+

Note: It is yet not possible to specify different devices for each subthread. This will require another split of the device structure into a device+subdevice tree.

In order to actually plug a media stream to an audio device you first have to decide whether you want the safe synchronous, or the experimental asynchronous way.

Due to the experimental status of asynchronous playback it has to be turned on explicitly.

— Variable: number-of-media-workers 4

Number of worker threads spawned as queue listeners.

— Function: init-asynchronousity

Initialise queue listener threads. The number of spawned worker threads can be controlled by number-of-media-workers. When called the complementary variable synchronous-sounds is set to nil.

— Function: uninit-asynchronousity

Stop all queue listener threads. Depending on whether there are busy threads this may block the main execution loop until all worker threads are non-busy. When called the complementary variable synchronous-sounds is set to t.

— Function: play-media-stream-synchronously stream &optional device sentinel volume

Play the media stream stream on an audio device synchronously. This function disregards the value of synchronous-sounds, instead streams will always be played in synchronous mode.

Optional second argument device must be an audio device created by make-audio-device. If omitted device defaults to the value of default-audio-device.

Optional third argument sentinel specifies a lisp function to be called after the stream playback finishes. The function should take one argument (stream) where stream is bound to the media stream which finished. See set-media-thread-sentinel.

Optional fourth argument volume specifies an initial value for the playback volume.

— Function: play-media-stream-asynchronously stream &optional device sentinel volume

Play the media stream stream on an audio device asynchronously. Return a media-thread object which can be used to interact with the worker thread which handles stream. This function disregards the value of synchronous-sounds, instead streams will always be played in asynchronous mode, provided the worker threads have been initialised. See init-asynchronousity.

Optional second argument device must be an audio device created by make-audio-device. If omitted device defaults to the value of default-audio-device.

Optional third argument sentinel specifies a lisp function to be called after the stream playback finishes. The function should take one argument (stream) where stream is bound to the media stream which finished. See set-media-thread-sentinel.

Optional fourth argument volume specifies an initial value for the playback volume.

To overcome the problem of deciding which of the playback functions to use, there is a wrapper function which does The Right Thing[tm].

— Variable: synchronous-sounds t

Play sounds synchronously, if non-nil. Only applies if SXEmacs has been compiled with a threading library. Otherwise, sounds are always played synchronously.

— Function: play-media-stream stream &optional device sentinel volume

Play the media stream stream on an audio device. stream must be a valid media-stream object as created by make-media-stream.

Optional second argument device must be an audio device created by make-audio-device. If omitted device defaults to the value of default-audio-device.

Optional third argument sentinel specifies a lisp function to be called after the stream playback finishes. The function should take one argument (stream) where stream is bound to the media stream which finished. See set-media-thread-sentinel.

Optional fourth argument volume specifies an initial value for the playback volume.

Depending on the value of synchronous-sounds this function will decide whether to play either asynchronously or synchronously.

If synchronous-sounds is nil and threads are supported, streams will be passed to the play-media-stream-asynchronously function. In that case return a media-thread object which can be used to interact with the worker thread which handles stream.

If synchronous-sounds is non-nil or threads are not supported, streams will be passed to the play-media-stream-synchronously function. In that case return non-nil if stream was played successfully, and nil otherwise.

See play-media-stream-synchronously and play-media-stream-asynchronously."

— Function: pause-media-thread thread

Pause the media thread thread. Optionally thread can be 'all in which case all running media threads are paused.

— Function: resume-media-thread thread

Resume a paused media thread thread. Optionally thread can be 'all in which case all paused media threads are resumed.

— Function: stop-media-thread thread

Stop a media thread thread. Optionally thread can be 'all in which case all media threads are stopped.

Stopping thread will unleash the respective worker threads. This is an irreversible action.

— Function: media-thread-set-volume thread volume

Set the volume of the media thread thread to volume.

thread is a media thread object with an audio substream. Optionally thread can be 'all in which case the volume change applies to all media threads.

volume is either a comparable number (see comparablep) or a vector of comparable numbers. In the former case volume sets the master volume of all channels. In the latter case volume sets the volumes channelwise.

Any volume value is coerced to an integer. A volume of 128 is the norm. A volume of 0 is muting the respective channels. A volume of 255 is the maximal volume, though clipping may occur. Volumes greater than 128 cause an amplification of the stream, 255 is the maximal value. Note that clipping may occur.

— Function: media-thread-volume thread

Return the current volume of media thread thread.

— Function: media-thread-set-rate thread rate

Set the rate of media thread thread to rate.

thread is a media thread object with an audio or video substream. Optionally thread can be 'all in which case the rate change applies to all media threads.

— Function: media-thread-rate thread

Return the current rate of media thread thread.

— Function: ding &optional arg sound device

Beep, or flash the frame. Also, unless an argument is given, terminate any keyboard macro currently executing. When called from lisp, the second argument is what sound to make, and the third argument is the device to make it in (defaults to the selected device), but may also be an audio device created by make-audio-device.

— Variable: sound-alist nil

An alist associating names with sounds. When beep or ding is called with one of the name symbols, the associated sound will be generated instead of the standard beep.

Each element of sound-alist is a list describing a sound. The first element of the list is the name of the sound being defined. Subsequent elements of the list are alternating keyword/value pairs:

Keyword: Value: ——— —— sound A string of raw sound data (deprecated), or the name of another sound to play. The symbol t here means use the default X beep. stream A media stream object containing the sound. volume An integer from 0-255, defaulting to bell-volume pitch If using the default X beep, the pitch (Hz) to generate. duration If using the default X beep, the duration (milliseconds).

You should probably add things to this list by calling the function load-sound-file.

Note: SXEmacs must be built with sound support for your system. Not all systems support sound. Note: The pitch, duration, and volume options are available everywhere, but many X servers ignore the pitch option.

The following beep-types are used by SXEmacs itself:

auto-save-error when an auto-save does not succeed command-error when the emacs command loop catches an error undefined-key when you type a key that is undefined undefined-click when you use an undefined mouse-click combination no-completion during completing-read y-or-n-p when you type something other than `y' or `n' yes-or-no-p when you type something other than `yes' or `no' default used when nothing else is appropriate.

Other lisp packages may use other beep types, but these are the ones that the C kernel of Emacs uses.

— Function: play-sound sound &optional volume device sentinel

Play the sound sound (a symbol) from sound-alist.

The sound is played at the specified volume (0-100, default specified by the bell-volume variable).

With no further media drivers, the sound file must be in the Sun/NeXT U-LAW format. Under Linux WAV files are also supported.

device can be any device created by make-audio-device and defaults to default-audio-device, or, if that is nil, to the selected device.

Optional argument sentinel specifies a lisp function to be called after the stream playback finishes. The function should take two arguments (stream state) where stream is bound to the media stream which finished and state is a symbol (currently the only valid symbol is 'finished). See set-media-thread-sentinel.

— Function: load-sound-file filename sound-name &optional volume

Read in an audio-file and add it to the sound-alist. The cached sound can be referenced later by sound-name.

filename can either be absolute or relative, in which case the file will be searched in the directories given by default-sound-directory-list. When looking for the file, the extensions given by sound-extension-list are also tried in the given order.