Previous: Audio Devices, Up: Media [Contents][Index]
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.
Number of worker threads spawned as queue listeners.
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.
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.
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.
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].
Play sounds synchronously, if non-nil.
Only applies if SXEmacs has been compiled with a threading library.
Otherwise, sounds are always played synchronously.
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."
Pause the media thread thread.
Optionally thread can be 'all in which case all running
media threads are paused.
Resume a paused media thread thread.
Optionally thread can be 'all in which case all paused
media threads are resumed.
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.
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.
Return the current volume of media thread thread.
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.
Return the current rate of media thread thread.
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.
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.
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.
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.
Previous: Audio Devices, Up: Media [Contents][Index]