2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 2005, 2006 Sebastian Freundt <hroptatyr@sxemacs.org>
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/media.info
7 @node Media, Hash Tables, Display, Top
8 @chapter Handling Media
10 This chapter describes a number of other features related to dealing
11 with media streams (such as audio or video).
13 Because SXEmacs' developers are lazy guys, or just annoyed to
14 re-invent a wheel, the current media facilities require a heap of other
15 libraries which themselves depend on more atomic libraries and so
19 * Prerequisites:: External library dependencies.
20 * Media Streams:: The concept of media streams.
21 * Audio Devices:: Audio output facilities.
22 * Media Threads:: Plugging a stream to an output device.
28 @section Prerequisites --- What do I need to start?
30 In order to use MM features with SXEmacs you need at least two
31 libraries. One of which is responsible for handling different types of
32 media files, that is parses them, demuxes them and decodes them to a raw
33 form suitable for your audio hardware. The other library cares for the
34 actual audio output, that is takes some raw audio data and feeds it to
35 your speakers (or somewhere else).
38 In the land of ASCII-arts diagrams this would translate to:
40 +------------+ +-----------+ +-------------+ +------------+
41 | media file | | media lib | | SXEmacs | | audio lib |
42 |------------|-->|-----------|-->|-------------|->|------------|->...
43 | e.g. | | parser | | bind to var | | connect to |
44 | .wav .mp3 | | demuxer | | start/stop | | soundcard |
45 | .ogg .mka | | decoder | | | | and play |
46 +------------+ +-----------+ +-------------+ +------------+
49 As can be seen, MM features will not work if either a media lib or an
50 audio lib is missing. SXEmacs supports a bunch of libraries in either
51 category. We discuss the supported audio libraries, their properties
52 and their availability first, afterwards we discuss the different media
57 {@bf The developers' recommendation is clearly to choose PulseAudio
58 as the audio library and FFmpeg as media library.}
61 The developers' recommendation is clearly to choose PulseAudio as the
62 audio library and FFmpeg as media library!
65 @subsection Audio Library: OSS (Open Sound System)
68 @item Availability: Linux and BSD systems only; ships with the linux kernel
69 @item Dependencies: none
72 @url{http://www.kernel.org}
74 @item Pros: easy consistent interface
75 @item Cons: old, ugly, depends too much on hardware
76 @item Known caveats with SXE: none
79 Since OSS was one of the most widespread architectures for audio many of
80 the new generation audio infrastructures support OSS with at least a
81 compatibility layer. For instance PulseAudio provides a tool
82 @samp{padsp}, and Esound calls it @samp{esddsp}. All these are
83 intended to provide an OSS device emulation for applications which
84 only speak OSS. All read/write accesses are rerouted to the
85 respective audio server.
88 @subsection Audio Library: NAS (Network Audio System)
91 @item Availability: Unix-wide
92 @item Dependencies: X, OSS
93 @item Webpage: @url{http://nas.codebrilliance.com/}
96 @url{http://nas.codebrilliance.com/nas/nas-1.8.src.tar.gz}
98 @item Pros: device independent, network-mode possible, mixing possible,
100 @item Cons: integrates to X, not recent, not very configurable
101 @item Known caveats with SXE: none
104 NAS was one of the audio systems which seized the concept of
105 X-Forwarding for audio data. Hence its name. However, large parts of
106 NAS depend on X which disqualifies it for non-local or tty-only use.
109 @subsection Audio Library: ESD (the enlightenment sound daemon)
112 @item Availability: Unix-wide
113 @item Dependencies: libaudiofile; optional: ALSA
114 @item Webpage: @url{http://developer.gnome.org/doc/whitepapers/esd/}
117 @url{ftp://ftp.gnome.org/pub/gnome/sources/esound/0.2/esound-0.2.36.tar.bz2}
120 device independent (if used with ALSA),
121 network-mode possible, mixing possible, small
123 high latency, not recent, not very configurable
124 @item Known caveats with SXE: none
127 Esound is a more decoupled approach but similar to NAS. Furthermore,
128 it provides transparent mixing facilities, applications just connect
129 to the Esound daemon and transfer the stream data, esd itself will
130 downmix the parallel streams and send it to the local sound
131 card. Hence it is well suited for local and network use.
134 @subsection Audio Library: PulseAudio (formerly known as PolypAudio)
137 @item Availability: Unix-wide
138 @item Dependencies: OSS, liboil, samplerate, libatomic_ops;
139 optional: ALSA, libasyncns, sndfile
140 @item Webpage: @url{http://pulseaudio.org/}
143 @url{http://0pointer.de/lennart/projects/pulseaudio/pulseaudio-0.9.5.tar.gz}
145 @url{svn co svn://0pointer.de/pulseaudio/trunk pulseaudio}
148 device independent (if used with ALSA),
149 network-mode possible, mixing possible, multiple inputs, multiple
150 outputs, low latency, very configurable, @emph{developers' choice}
152 unstable with many simultaneous connections
153 @item Known caveats with SXE: none
156 PulseAudio is one of the most advanced new-generation audio servers.
157 It is modular, supports local and network connections, provides
158 transparent downmixing of incoming streams (like esd) and is fully
159 compatible to esd. Furthermore, you can use sound in both directions,
160 i.e. record from pulse sources. Pulse provides modules to not only
161 directly attach to local hardware but also to other remotely running
162 pulses or other running audio servers (like jack, esd, etc.).
165 @subsection Audio Library: Jack (a low-latency audio server)
168 @item Availability: Unix-wide
169 @item Dependencies: ALSA
170 @item Webpage: @url{http://jackit.sourceforge.net/}
173 @url{http://prdownloads.sourceforge.net/jackit/},
175 @url{cvs -z3 -d:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/jackit co jack}
178 high accuracy, extreme low latency, device independent, mixing possible
181 @item Known caveats with SXE: none
184 JACK is a low-latency audio server, written for POSIX conformant
185 operating systems such as GNU/Linux and Apple's OS X. It can connect a
186 number of different applications to an audio device, as well as allowing
187 them to share audio between themselves. Its clients can run in their own
188 processes (ie. as normal applications), or can they can run within the
189 JACK server (ie. as a "plugin").
191 JACK was designed from the ground up for professional audio work, and
192 its design focuses on two key areas: synchronous execution of all
193 clients, and low latency operation.
196 @subsection Audio Library: ao (generic and portable audio output)
199 @item Availability: Unix-wide
200 @item Optional Dependencies: OSS, ALSA, polyp, esd, sunaudio, NAS
201 @item Webpage: @url{http://www.xiph.org/ao/}
204 @url{http://downloads.xiph.org/releases/ao/libao-0.8.6.tar.gz},
206 @url{svn co http://svn.xiph.org/trunk/ao ao}
209 portable, wrapper library around system libraries
211 @item Known caveats with SXE: none
214 Libao is a cross-platform audio library that allows programs to output
215 audio using a simple API on a wide variety of platforms. It currently
216 supports Null output (handy for testing without a sound device), OSS,
217 ALSA, polypaudio (next generation GNOME sound server), esd (EsounD or
218 Enlightened Sound Daemon), AIX, Sun/NetBSD/OpenBSD, IRIX, NAS
221 @subsection Audio Library: alsa (Advanced Linux Sound Architecture)
224 @item Availability: Linux
225 @item Dependencies: ALSA kernel modules
226 @item Webpage: @url{http://www.alsa-project.org/}
229 @url{ftp://ftp.alsa-project.org/pub/lib/}
231 @url{hg clone http://hg-mirror.alsa-project.org/alsa-lib alsa-lib}
234 mature, SMP and thread-safe design
236 only available under linux, needs kernel support
237 @item Known caveats with SXE: none
242 @subsection Media Library: sndfile
245 @item Availability: Unix-wide
246 @item Dependencies: none
247 @item Webpage: @url{http://www.mega-nerd.com/libsndfile/}
250 @url{http://www.mega-nerd.com/libsndfile/libsndfile-1.0.15.tar.gz}
252 @item Maximally provided formats:
254 @item Known caveats with SXE: none
258 @subsection Media Library: ffmpeg
261 @item Availability: Unix-wide
262 @item Optional Dependencies: mp3lame, libogg, libvorbis, theora, faad,
263 faac, xvid, x264, a52dec, libdts, amr_nb, amr_wb, amr_if2, Flac,
265 @item Webpage: @url{http://ffmpeg.sourceforge.net/}
268 @url{cvs -z3 -d:pserver:anonymous@@mplayerhq.hu:/cvsroot/ffmpeg co ffmpeg}
270 @item Maximally provided formats: a52, ac3, adpcm, adx, .mp2, .mp3,
271 Ogg/Vorbis, theora, AAC, xvid, mpeg1-video, mpeg-audio, h.264, h.263,
272 h.263p, FLV, RealVideo 1.0, RealVideo 2.0, MPEG-4, WMV1, WMV2, SVQ,
273 MJPEG, LJPEG, JPEGls, .jpeg, .png, .ppm, .pgm, YUV, .pbm, .pam, .bmp,
274 Huffman-YUV, ASV, Snow, Sonic, DV captures, x264, GSM, Indeo2/3, TSCC,
275 CSCD, nuppel-video, Qdraw, Qpeg, Loco, Fraps, Xvmc, MACE3/6, CLJR, ROQ,
276 ROQ Dpcm, interplay video, interplay Dpcm, Xan-WC3, RPZA, Cinepak,
277 MS-RLE, VQA, 8bps, SMC, flac, truemotion1/2, VMD-Video, VMD-Audio, ZMBV,
278 Smacker, .dts, RealAudio-144, RealAudio-288, Qt-RLE, Cook, Truespeech,
279 TTA, AVS, AMR Narrowband, AMR Wideband, ADPCM WAV, PCM/WAV,
280 DVD-Subtitles, h.261, ASF, matroska, ShockWave Flash, Apple .mov, MP4,
281 Westwood, V4L, V4L2, MPEG-PS, DV1394, RealMedia, RTP/RTSP, SGI .aiff,
283 @item Notes: Only recent CVS versions are fully supported
284 @item Known caveats with SXE: none
287 FFmpeg has always been a very experimental and developer-driven
288 project. It is a key component in many multimedia projects and has new
289 features added constantly. New, official "releases" are few and far
290 between. In short, if you want to work with FFmpeg, you are advised to
291 go along with CVS development rather than relying on formal
292 releases. CVS snapshots work really well 99% of the time so people are
293 not afraid to use them.
296 Sample @samp{./configure}-line:
298 ./configure --enable-shared --enable-static --enable-mp3lame \
299 --enable-libogg --enable-vorbis --enable-theora --enable-faad \
300 --enable-faadbin --enable-faac --enable-xvid --enable-x264 \
301 --enable-a52 --enable-a52bin --enable-dts --enable-pp \
302 --enable-amr_nb --enable-amr_wb --enable-amr_if2 \
303 --enable-pthreads --enable-gpl
307 @subsection Media Library: mad
310 @item Availability: Unix-wide
311 @item Dependencies: none
312 @item Webpage: @url{http://www.underbit.com/products/mad/}
315 @url{ftp://ftp.mars.org/pub/mpeg/libmad-0.15.1b.tar.gz}
317 @item Maximally provided formats: mpeg-audio .mpa, .mp2, .mp3
318 @item Notes: seems discontinued, not recent
319 @item Known caveats with SXE: none
322 MAD is a high-quality MPEG audio decoder. It currently supports MPEG-1
323 and the MPEG-2 extension to lower sampling frequencies, as well as the
324 de facto MPEG 2.5 format. All three audio layers -- Layer I, Layer
325 II, and Layer III (i.e. MP3) -- are fully implemented.
327 MAD does not yet support MPEG-2 multichannel audio (although it should
328 be backward compatible with such streams) nor does it currently support
333 @subsection Media Library: SoX
336 @item Availability: Unix-wide
337 @item Dependencies: none
338 @item Webpage: @url{http://sox.sourceforge.net/}
341 @url{http://prdownloads.sourceforge.net/sox/sox-12.17.9.tar.gz}
343 @item Maximally provided formats: raw, 8svx, SGI .aiff, Sun .au, .snd, AVR,
344 GSM raw, HCOM, MAUD, mp3, TX-16w, .voc, ADPCM .vox, .wav, RIFX, ADPCM
345 WAV, Ogg/Vorbis, A-law, .wve
346 @item Notes: must do @samp{make install-lib}
347 @item Known caveats with SXE: none
351 @subsection Media Library: xine
354 @item Availability: Unix-wide
355 @item Dependencies: none
356 @item Webpage: @url{http://xinehq.de/}
359 @url{http://prdownloads.sourceforge.net/xine/xine-lib-1.1.1.tar.gz}
361 @url{cvs -z3 -d:pserver:anonymous@@cvs.sf.net:/cvsroot/xine co xine-lib}
363 @item Maximally provided formats:
365 @item Known caveats with SXE: not working
369 @subsection Media Library: gstreamer
372 @item Availability: Unix-wide
373 @item Dependencies: none
374 @item Webpage: @url{http://gstreamer.freedesktop.org/}
377 @url{http://gstreamer.freedesktop.org/src/gstreamer/gstreamer-0.10.4.tar.bz2}
379 @url{cvs -z3 -d:pserver:anoncvs@@anoncvs.freedesktop.org:/cvs/gstreamer co gstreamer}
381 @item Maximally provided formats:
383 @item Known caveats with SXE: not working
387 @subsection Built-in media file handling
390 @item Availability: Unix-wide
391 @item Dependencies: none
394 @item Maximally provided formats: .wav, RIFX, Sun .au
395 @item Notes: ugly and old
396 @item Known caveats with SXE: very limited, very slow
402 @section Media Streams
404 SXEmacs provides a common and opaque API to all of the above
405 libraries. Media files or streams are encapsulated into media stream
406 objects, which behave equally whatever library is used to parse them.
409 The fundamental function to create such media streams is
410 @code{make-media-stream}.
412 @defun make-media-stream from data &optional driver
413 Create a new media stream from @var{data}.
414 @var{from} is a keyword and defines how @var{data} is
416 @code{:file} - @var{data} is the name of a file
417 @code{:data} - @var{data} is a string with the stream data
418 @code{:url} - @var{data} is a url (string) for streamed media contents
420 Optional argument @var{driver} (a symbol) may be used to force
421 the use of a certain driver instead of automatically
422 detecting a suitable one. It is one of @samp{ffmpeg}, @samp{sndfile},
423 @samp{sox}, @samp{mad}, @samp{xine}, @samp{gstreamer}, or @samp{internal}.
426 Hereby, the media driver which is used in order to handle the
427 resulting media stream is chosen automatically. Portions of the data
428 are passed to all available media APIs, that is all APIs which have been
429 configured at compile time. The first such API which parses the portion
430 successfully is chosen as driver.
433 (make-media-stream :file "/home/media/audio/Bloke.mp3")
434 @result{} #<media-stream :kind #<file "/home/media/audio/Bloke.mp3">
435 #<media-substream :type #<audio mp3 (mp3), stereo, 44100 Hz, 16 Bit, 128
436 kb/s>> driven by ffmpeg :author "Chris Franklin " :title: "Bloke " :year
440 Media stream objects contain information about where to find a medium,
441 the characteristics (like number of channels, sample rate, resolution),
442 which demuxer and which decoder to use, and some informational extras.
443 They do not contain the medium itself nor a raw (i.e. undecoded) form
444 nor portions of these. Hence, if you want to use a media stream object
445 after its creation you should make sure that it still exists.
447 Media streams usually consist of several substreams internally. These
448 substreams each represent a certain partition of the whole stream. If
449 you regard an ordinary movie DVD, the media stream with location
450 @samp{/path/dvd-drive} would be made up of a substream which contains
451 the motion picture, a substream which contains a language track, other
452 audio track substreams which contain the further languages, possibly a
453 substream for subtitles and so forth.
456 Substreams cannot be accessed individually nor extracted. This may
457 change in the future.
462 @section Audio Devices
464 Considering media stream objects as sources for multimedia playback,
465 the targets are obviously X displays, buffers and/or sound cards or
468 Like media stream objects, audio device objects are containers for the
469 underlying driver libraries.
471 @defun make-audio-device driver &rest device-options
472 Create a new device to output audio via @var{driver}.
473 @var{driver} should be a symbol out of 'oss, 'nas, 'esd, 'pulse,
474 'jack, 'alsa, or 'ao.
476 The rest arguments may be used to pass options to the selected
477 output driver. These should be `:keyword value' pairs.
479 Valid keywords for ALSA are:
480 :device - the name of the hardware interface (default: "default"),
481 you may want to try "plughw:0,0" first
482 :keep-open - whether to exclusively reserve the device.
483 Note this may prevent other applications from using the device.
485 Valid keywords for (deprecated) OSS are:
486 :device - the name of the hardware interface (default: "/dev/dsp")
487 :keep-open - whether to exclusively reserve the device.
488 Note this may prevent other applications from using the device.
490 Valid keywords for ESD are:
491 :server - to use a distant ESD daemon (e.g. "my.machine.box:16001")
492 The default for ESD output is to use a locally running daemon and
493 to connect to it via unix domain sockets.
495 Valid keywords for Pulse are:
496 :server - the host name to connect to (default: "localhost")
497 :sink - the name of the sink to connect to (e.g. "output")
498 :source - the name of the source to record from (e.g. "mic_in")
499 :client - how to call the client on the server (default "SXEmacs")
500 :stream - how to call the stream on the server (e.g. "fancy-sound")
501 :immediate - connect to sink immediately and keep the connection
502 alive as long as the audio device exists (default `t')
503 :threaded - initiate a threaded mainloop (default `t')
504 :force - if non-`nil' the device object is created even though the
505 pulse mainloop could not be started; if `nil' any mainloop failure
506 results in an error. This can be useful if you want to have an
507 audio device object although the server is not (yet) up or not
508 (yet) accepting connections from you. (default `nil')
510 Valid keywords for Jack are:
511 :server - the jack server to connect to (default "default")
512 :client - how to call the client on the server (default "SXEmacs")
514 Valid keywords for AO are:
515 :driver - the name of the output driver (e.g. "alsa", "esd", etc.)
516 :options - a list of AO suboptions (see AO documentation)
517 The default for AO output is to pass nothing and entirely use the
518 system and user configuration files.
520 Valid keywords for NAS are:
521 :server - the NAS server to connect to. This can be either:
522 - an X display string like "localhost:0.0", the X display string
523 the current frame is on can be obtained by the function
525 - or a SXEmacs device name like "localhost-11-0" which can be
526 obtained by `device-name'
527 - or a SXEmacs device object, obtainable by `frame-device', like
528 #<x-device on "localhost:11.0" 0xee4>
529 If the :server keyword is omitted SXEmacs tries to determine a
530 sensible default in this order:
531 - use the frame device of the current frame
532 - use the frame device of the initial frame
533 - use the display specified in $AUDIOSERVER
534 - use the display specified in $DISPLAY
535 - try "localhost:0.0"
541 (make-audio-device 'pulse)
542 @result{} #<audio-device :type pulse :server #default :sink #default
543 :source #default :server-state #connected :api #threaded
544 :mainloop 0x973f8c0 :device-state #unknown>
548 (make-audio-device 'jack)
549 @result{} #<audio-device :type jack :server #default :client SXEmacs
550 :device-state #unknown>
554 @defun audio-device-p object
555 Return non-@code{nil} if @var{object} is an audio-device, @code{nil}
559 @defvar default-audio-device nil
560 Default audio device to use.
565 @section Media Threads
567 Media threads can be thought of a way to plug a certain media stream
568 into a certain output device. Since SXEmacs merely supports audio
569 output devices the only partition which is finally ``played'' is an
572 @c This changeset completely splits up the Thread and Stream types into trees. This
573 @c allows to have several substreams embedded into a stream, respectively several
574 @c subthreads can be started from a thread.
576 The current structure looks like:
580 +------------> Stream <------------+
584 substream1 <-----> substream2 <-----> substream3
588 Similarly for Threads:
592 +------------> Thread <------------+
596 subthread1 <-----> subthread2 <-----> subthread3
601 To be precise, threads are the containers for the streams. Streams are stored
602 (along with devices) inside threads, while substreams are stored inside
603 subthreads. In source/sink language, a thread is the cable to plug a source
604 (stream) to a sink (device).
610 ,-----> | Thread | <-----,
621 +==========+ next +==========+ next +==========+
622 |subthread1| <-----> |subthread2| <-----> |subthread3|
623 +----------+ prev +----------+ prev +----------+
624 |substream1| |substream2| |substream3|
625 |pthread_t1| |pthread_t2| |pthread_t3|
626 |privdata1 | |privdata2 | |privdata3 |
627 +==========+ +==========+ +==========+
630 Note: It is yet @emph{not} possible to specify different devices for
631 each subthread. This will require another split of the device
632 structure into a device+subdevice tree.
634 In order to actually plug a media stream to an audio device you first
635 have to decide whether you want the safe synchronous, or the
636 experimental asynchronous way.
638 Due to the experimental status of asynchronous playback it has to be
639 turned on explicitly.
641 @defvar number-of-media-workers 4
642 Number of worker threads spawned as queue listeners.
645 @defun init-asynchronousity
646 Initialise queue listener threads.
647 The number of spawned worker threads can be controlled by
648 @code{number-of-media-workers}.
649 When called the complementary variable @code{synchronous-sounds} is
653 @defun uninit-asynchronousity
654 Stop all queue listener threads.
655 Depending on whether there are busy threads this may block the
656 main execution loop until all worker threads are non-busy.
657 When called the complementary variable @code{synchronous-sounds} is
661 @defun play-media-stream-synchronously stream &optional device sentinel volume
662 Play the media stream @var{stream} on an audio device synchronously.
663 This function disregards the value of @code{synchronous-sounds},
664 instead streams will always be played in synchronous mode.
666 Optional second argument @var{device} must be an audio device created
667 by @code{make-audio-device}.
668 If omitted @var{device} defaults to the value of
669 @code{default-audio-device}.
671 Optional third argument @var{sentinel} specifies a lisp function to be
672 called after the stream playback finishes. The function should
673 take one argument (@var{stream}) where @var{stream} is bound to the
674 media stream which finished. See @code{set-media-thread-sentinel}.
676 Optional fourth argument @code{volume} specifies an initial value for
680 @defun play-media-stream-asynchronously stream &optional device sentinel volume
681 Play the media stream @var{stream} on an audio device asynchronously.
682 Return a media-thread object which can be used to interact with
683 the worker thread which handles @var{stream}.
684 This function disregards the value of @code{synchronous-sounds},
685 instead streams will always be played in asynchronous mode,
686 provided the worker threads have been initialised.
687 See @code{init-asynchronousity}.
689 Optional second argument @var{device} must be an audio device created
690 by @code{make-audio-device}.
691 If omitted @code{device} defaults to the value of
692 @code{default-audio-device}.
694 Optional third argument @var{sentinel} specifies a lisp function to be
695 called after the stream playback finishes. The function should
696 take one argument (@var{stream}) where @var{stream} is bound to the
697 media stream which finished. See @code{set-media-thread-sentinel}.
699 Optional fourth argument @code{volume} specifies an initial value for
703 To overcome the problem of deciding which of the playback functions to
704 use, there is a wrapper function which does The Right Thing@sc{[tm]}.
706 @defvar synchronous-sounds t
707 Play sounds synchronously, if non-@code{nil}.
708 Only applies if SXEmacs has been compiled with a threading library.
709 Otherwise, sounds are always played synchronously.
712 @defun play-media-stream stream &optional device sentinel volume
713 Play the media stream @var{stream} on an audio device.
714 @var{stream} must be a valid media-stream object as created by
715 @code{make-media-stream}.
717 Optional second argument @var{device} must be an audio device created
718 by @code{make-audio-device}.
719 If omitted @var{device} defaults to the value of
720 @code{default-audio-device}.
722 Optional third argument @var{sentinel} specifies a lisp function to be
723 called after the stream playback finishes. The function should
724 take one argument (@var{stream}) where @var{stream} is bound to the
725 media stream which finished. See @code{set-media-thread-sentinel}.
727 Optional fourth argument @var{volume} specifies an initial value for
731 Depending on the value of @code{synchronous-sounds} this function will
732 decide whether to play either asynchronously or synchronously.
734 If @code{synchronous-sounds} is @code{nil} @emph{and} threads are
735 supported, streams will be passed to the
736 @code{play-media-stream-asynchronously} function.
737 In that case return a media-thread object which can be used to
738 interact with the worker thread which handles @var{stream}.
740 If @code{synchronous-sounds} is non-@code{nil} @emph{or} threads are
741 not supported, streams will be passed to the
742 @code{play-media-stream-synchronously} function.
743 In that case return non-@code{nil} if @var{stream} was played
744 successfully, and @code{nil} otherwise.
746 See @code{play-media-stream-synchronously} and
747 @code{play-media-stream-asynchronously}."
751 @defun pause-media-thread thread
752 Pause the media thread @var{thread}.
753 Optionally @var{thread} can be @code{'all} in which case all running
754 media threads are paused.
757 @defun resume-media-thread thread
758 Resume a paused media thread @var{thread}.
759 Optionally @var{thread} can be @code{'all} in which case all paused
760 media threads are resumed.
763 @defun stop-media-thread thread
764 Stop a media thread @var{thread}.
765 Optionally @var{thread} can be @code{'all} in which case all media
768 Stopping @var{thread} will unleash the respective worker threads.
769 This is an irreversible action.
772 @defun media-thread-set-volume thread volume
773 Set the volume of the media thread @var{thread} to @var{volume}.
775 @var{thread} is a media thread object with an audio substream.
776 Optionally @var{thread} can be @code{'all} in which case the volume
777 change applies to all media threads.
779 @var{volume} is either a comparable number (see @code{comparablep}) or
780 a vector of comparable numbers.
781 In the former case @var{volume} sets the master volume of all channels.
782 In the latter case @var{volume} sets the volumes channelwise.
784 Any volume value is coerced to an integer.
785 A volume of 128 is the norm.
786 A volume of 0 is muting the respective channels.
787 A volume of 255 is the maximal volume, though clipping may occur.
788 Volumes greater than 128 cause an amplification of the stream,
789 255 is the maximal value. Note that clipping may occur.
792 @defun media-thread-volume thread
793 Return the current volume of media thread @var{thread}.
796 @defun media-thread-set-rate thread rate
797 Set the rate of media thread @var{thread} to @var{rate}.
799 @var{thread} is a media thread object with an audio or video
800 substream. Optionally @var{thread} can be @code{'all} in which case
801 the rate change applies to all media threads.
804 @defun media-thread-rate thread
805 Return the current rate of media thread @var{thread}.
809 @defun ding &optional arg sound device
810 Beep, or flash the frame.
811 Also, unless an argument is given,
812 terminate any keyboard macro currently executing.
813 When called from lisp, the second argument is what sound to make, and
814 the third argument is the device to make it in (defaults to the selected
815 device), but may also be an audio device created by
816 @code{make-audio-device}.
820 @c sounds by symbol voodoo
822 @defvar sound-alist nil
823 An alist associating names with sounds.
824 When @code{beep} or @code{ding} is called with one of the name
825 symbols, the associated sound will be generated instead of the
828 Each element of @code{sound-alist} is a list describing a sound.
829 The first element of the list is the name of the sound being defined.
830 Subsequent elements of the list are alternating keyword/value pairs:
834 sound A string of raw sound data (deprecated), or the name of another
835 sound to play. The symbol @code{t} here means use the
837 stream A media stream object containing the sound.
838 volume An integer from 0-255, defaulting to @code{bell-volume}
839 pitch If using the default X beep, the pitch (Hz) to generate.
840 duration If using the default X beep, the duration (milliseconds).
842 You should probably add things to this list by calling the function
843 @code{load-sound-file}.
845 Note: SXEmacs must be built with sound support for your system. Not all
846 systems support sound.
847 Note: The pitch, duration, and volume options are available everywhere,
848 but many X servers ignore the @code{pitch} option.
850 The following beep-types are used by SXEmacs itself:
852 auto-save-error when an auto-save does not succeed
853 command-error when the emacs command loop catches an error
854 undefined-key when you type a key that is undefined
855 undefined-click when you use an undefined mouse-click combination
856 no-completion during completing-read
857 y-or-n-p when you type something other than `y' or `n'
858 yes-or-no-p when you type something other than `yes' or `no'
859 default used when nothing else is appropriate.
861 Other lisp packages may use other beep types, but these are the ones that
862 the C kernel of Emacs uses.
865 @c moved from display.texi
866 @defun play-sound sound &optional volume device sentinel
867 Play the sound @var{sound} (a symbol) from @var{sound-alist}.
869 The sound is played at the specified @var{volume} (0-100, default
870 specified by the @var{bell-volume} variable).
872 With no further media drivers, the sound file must be in the
873 Sun/NeXT U-LAW format. Under Linux WAV files are also supported.
875 @var{device} can be any device created by @code{make-audio-device}
876 and defaults to @var{default-audio-device}, or, if that is @code{nil},
877 to the selected device.
879 Optional argument @var{sentinel} specifies a lisp function to be
880 called after the stream playback finishes. The function should
881 take two arguments (@var{stream} @var{state}) where @var{stream}
882 is bound to the media stream which finished and @var{state} is a
883 symbol (currently the only valid symbol is @code{'finished}).
884 See @code{set-media-thread-sentinel}.
887 @defun load-sound-file filename sound-name &optional volume
888 Read in an audio-file and add it to the sound-alist.
889 The cached sound can be referenced later by @var{sound-name}.
891 @var{filename} can either be absolute or relative, in which case the
892 file will be searched in the directories given by
893 @code{default-sound-directory-list}.
894 When looking for the file, the extensions given by
895 @code{sound-extension-list} are also tried in the given order.
899 @c @c @c media.texi ends here