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 spread 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}, Esound calls it @samp{esddsp}, and @samp{artsdsp} is the
83 arts version. All these are intended to provide an OSS device
84 emulation for applications which only speak OSS. All read/write
85 accesses are rerouted to the 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: aRts (the analog realtime synthesizer)
168 @item Availability: Unix-wide
169 @item Dependencies: OSS, (KDE);
170 optional: ALSA, Jack, ESD, mas, NAS, libaudiofile, Qt, sgilibaudio
171 @item Webpage: @url{http://www.arts-project.org/}
174 @url{ftp://ftp.kde.org/pub/kde/stable/latest/src/arts-1.5.2.tar.bz2},
177 @url{http://arts-project.org/download/arts-0.5.4.tar.gz}
180 device independent (if used with ALSA or other sound servers),
181 network-mode possible, mixing possible, very flexible, very configurable
183 standalone version discontinued, lots of processes, uses/needs MCOP
184 @item Known caveats with SXE: none
187 Arts was designed as both audio server and synthesizer originally.
188 It is usable locally and transparently downmixes incoming streams.
189 However, since starting arts (even the standalone artsd) means
190 starting 80% of a bloated KDE, we highly discourage its use.
193 @subsection Audio Library: Jack (a low-latency audio server)
196 @item Availability: Unix-wide
197 @item Dependencies: ALSA
198 @item Webpage: @url{http://jackit.sourceforge.net/}
201 @url{http://prdownloads.sourceforge.net/jackit/},
203 @url{cvs -z3 -d:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/jackit co jack}
206 high accuracy, extreme low latency, device independent, mixing possible
209 @item Known caveats with SXE: none
212 JACK is a low-latency audio server, written for POSIX conformant
213 operating systems such as GNU/Linux and Apple's OS X. It can connect a
214 number of different applications to an audio device, as well as allowing
215 them to share audio between themselves. Its clients can run in their own
216 processes (ie. as normal applications), or can they can run within the
217 JACK server (ie. as a "plugin").
219 JACK was designed from the ground up for professional audio work, and
220 its design focuses on two key areas: synchronous execution of all
221 clients, and low latency operation.
224 @subsection Audio Library: ao (generic and portable audio output)
227 @item Availability: Unix-wide
228 @item Optional Dependencies: OSS, ALSA, polyp, esd, sunaudio, NAS
229 @item Webpage: @url{http://www.xiph.org/ao/}
232 @url{http://downloads.xiph.org/releases/ao/libao-0.8.6.tar.gz},
234 @url{svn co http://svn.xiph.org/trunk/ao ao}
237 portable, wrapper library around system libraries
239 @item Known caveats with SXE: none
242 Libao is a cross-platform audio library that allows programs to output
243 audio using a simple API on a wide variety of platforms. It currently
244 supports Null output (handy for testing without a sound device), OSS,
245 ALSA, polypaudio (next generation GNOME sound server), esd (EsounD or
246 Enlightened Sound Daemon), AIX, Sun/NetBSD/OpenBSD, IRIX, NAS
249 @subsection Audio Library: alsa (Advanced Linux Sound Architecture)
252 @item Availability: Linux
253 @item Dependencies: ALSA kernel modules
254 @item Webpage: @url{http://www.alsa-project.org/}
257 @url{ftp://ftp.alsa-project.org/pub/lib/}
259 @url{hg clone http://hg-mirror.alsa-project.org/alsa-lib alsa-lib}
262 mature, SMP and thread-safe design
264 only available under linux, needs kernel support
265 @item Known caveats with SXE: none
270 @subsection Media Library: sndfile
273 @item Availability: Unix-wide
274 @item Dependencies: none
275 @item Webpage: @url{http://www.mega-nerd.com/libsndfile/}
278 @url{http://www.mega-nerd.com/libsndfile/libsndfile-1.0.15.tar.gz}
280 @item Maximally provided formats:
282 @item Known caveats with SXE: none
286 @subsection Media Library: ffmpeg
289 @item Availability: Unix-wide
290 @item Optional Dependencies: mp3lame, libogg, libvorbis, theora, faad,
291 faac, xvid, x264, a52dec, libdts, amr_nb, amr_wb, amr_if2, Flac,
293 @item Webpage: @url{http://ffmpeg.sourceforge.net/}
296 @url{cvs -z3 -d:pserver:anonymous@@mplayerhq.hu:/cvsroot/ffmpeg co ffmpeg}
298 @item Maximally provided formats: a52, ac3, adpcm, adx, .mp2, .mp3,
299 Ogg/Vorbis, theora, AAC, xvid, mpeg1-video, mpeg-audio, h.264, h.263,
300 h.263p, FLV, RealVideo 1.0, RealVideo 2.0, MPEG-4, WMV1, WMV2, SVQ,
301 MJPEG, LJPEG, JPEGls, .jpeg, .png, .ppm, .pgm, YUV, .pbm, .pam, .bmp,
302 Huffman-YUV, ASV, Snow, Sonic, DV captures, x264, GSM, Indeo2/3, TSCC,
303 CSCD, nuppel-video, Qdraw, Qpeg, Loco, Fraps, Xvmc, MACE3/6, CLJR, ROQ,
304 ROQ Dpcm, interplay video, interplay Dpcm, Xan-WC3, RPZA, Cinepak,
305 MS-RLE, VQA, 8bps, SMC, flac, truemotion1/2, VMD-Video, VMD-Audio, ZMBV,
306 Smacker, .dts, RealAudio-144, RealAudio-288, Qt-RLE, Cook, Truespeech,
307 TTA, AVS, AMR Narrowband, AMR Wideband, ADPCM WAV, PCM/WAV,
308 DVD-Subtitles, h.261, ASF, matroska, ShockWave Flash, Apple .mov, MP4,
309 Westwood, V4L, V4L2, MPEG-PS, DV1394, RealMedia, RTP/RTSP, SGI .aiff,
311 @item Notes: Only recent CVS versions are fully supported
312 @item Known caveats with SXE: none
315 FFmpeg has always been a very experimental and developer-driven
316 project. It is a key component in many multimedia projects and has new
317 features added constantly. New, official "releases" are few and far
318 between. In short, if you want to work with FFmpeg, you are advised to
319 go along with CVS development rather than relying on formal
320 releases. CVS snapshots work really well 99% of the time so people are
321 not afraid to use them.
324 Sample @samp{./configure}-line:
326 ./configure --enable-shared --enable-static --enable-mp3lame \
327 --enable-libogg --enable-vorbis --enable-theora --enable-faad \
328 --enable-faadbin --enable-faac --enable-xvid --enable-x264 \
329 --enable-a52 --enable-a52bin --enable-dts --enable-pp \
330 --enable-amr_nb --enable-amr_wb --enable-amr_if2 \
331 --enable-pthreads --enable-gpl
335 @subsection Media Library: mad
338 @item Availability: Unix-wide
339 @item Dependencies: none
340 @item Webpage: @url{http://www.underbit.com/products/mad/}
343 @url{ftp://ftp.mars.org/pub/mpeg/libmad-0.15.1b.tar.gz}
345 @item Maximally provided formats: mpeg-audio .mpa, .mp2, .mp3
346 @item Notes: seems discontinued, not recent
347 @item Known caveats with SXE: none
350 MAD is a high-quality MPEG audio decoder. It currently supports MPEG-1
351 and the MPEG-2 extension to lower sampling frequencies, as well as the
352 de facto MPEG 2.5 format. All three audio layers -- Layer I, Layer
353 II, and Layer III (i.e. MP3) -- are fully implemented.
355 MAD does not yet support MPEG-2 multichannel audio (although it should
356 be backward compatible with such streams) nor does it currently support
361 @subsection Media Library: SoX
364 @item Availability: Unix-wide
365 @item Dependencies: none
366 @item Webpage: @url{http://sox.sourceforge.net/}
369 @url{http://prdownloads.sourceforge.net/sox/sox-12.17.9.tar.gz}
371 @item Maximally provided formats: raw, 8svx, SGI .aiff, Sun .au, .snd, AVR,
372 GSM raw, HCOM, MAUD, mp3, TX-16w, .voc, ADPCM .vox, .wav, RIFX, ADPCM
373 WAV, Ogg/Vorbis, A-law, .wve
374 @item Notes: must do @samp{make install-lib}
375 @item Known caveats with SXE: none
379 @subsection Media Library: xine
382 @item Availability: Unix-wide
383 @item Dependencies: none
384 @item Webpage: @url{http://xinehq.de/}
387 @url{http://prdownloads.sourceforge.net/xine/xine-lib-1.1.1.tar.gz}
389 @url{cvs -z3 -d:pserver:anonymous@@cvs.sf.net:/cvsroot/xine co xine-lib}
391 @item Maximally provided formats:
393 @item Known caveats with SXE: not working
397 @subsection Media Library: gstreamer
400 @item Availability: Unix-wide
401 @item Dependencies: none
402 @item Webpage: @url{http://gstreamer.freedesktop.org/}
405 @url{http://gstreamer.freedesktop.org/src/gstreamer/gstreamer-0.10.4.tar.bz2}
407 @url{cvs -z3 -d:pserver:anoncvs@@anoncvs.freedesktop.org:/cvs/gstreamer co gstreamer}
409 @item Maximally provided formats:
411 @item Known caveats with SXE: not working
415 @subsection Built-in media file handling
418 @item Availability: Unix-wide
419 @item Dependencies: none
422 @item Maximally provided formats: .wav, RIFX, Sun .au
423 @item Notes: ugly and old
424 @item Known caveats with SXE: very limited, very slow
430 @section Media Streams
432 SXEmacs provides a common and opaque API to all of the above
433 libraries. Media files or streams are encapsulated into media stream
434 objects, which behave equally whatever library is used to parse them.
437 The fundamental function to create such media streams is
438 @code{make-media-stream}.
440 @defun make-media-stream from data &optional driver
441 Create a new media stream from @var{data}.
442 @var{from} is a keyword and defines how @var{data} is
444 @code{:file} - @var{data} is the name of a file
445 @code{:data} - @var{data} is a string with the stream data
446 @code{:url} - @var{data} is a url (string) for streamed media contents
448 Optional argument @var{driver} (a symbol) may be used to force
449 the use of a certain driver instead of automatically
450 detecting a suitable one. It is one of @samp{ffmpeg}, @samp{sndfile},
451 @samp{sox}, @samp{mad}, @samp{xine}, @samp{gstreamer}, or @samp{internal}.
454 Hereby, the media driver which is used in order to handle the
455 resulting media stream is chosen automatically. Portions of the data
456 are passed to all available media APIs, that is all APIs which have been
457 configured at compile time. The first such API which parses the portion
458 successfully is chosen as driver.
461 (make-media-stream :file "/home/media/audio/Bloke.mp3")
462 @result{} #<media-stream :kind #<file "/home/media/audio/Bloke.mp3">
463 #<media-substream :type #<audio mp3 (mp3), stereo, 44100 Hz, 16 Bit, 128
464 kb/s>> driven by ffmpeg :author "Chris Franklin " :title: "Bloke " :year
468 Media stream objects contain information about where to find a medium,
469 the characteristics (like number of channels, sample rate, resolution),
470 which demuxer and which decoder to use, and some informational extras.
471 They do not contain the medium itself nor a raw (i.e. undecoded) form
472 nor portions of these. Hence, if you want to use a media stream object
473 after its creation you should make sure that it still exists.
475 Media streams usually consist of several substreams internally. These
476 substreams each represent a certain partition of the whole stream. If
477 you regard an ordinary movie DVD, the media stream with location
478 @samp{/path/dvd-drive} would be made up of a substream which contains
479 the motion picture, a substream which contains a language track, other
480 audio track substreams which contain the further languages, possibly a
481 substream for subtitles and so forth.
484 Substreams cannot be accessed individually nor extracted. This may
485 change in the future.
490 @section Audio Devices
492 Considering media stream objects as sources for multimedia playback,
493 the targets are obviously X displays, buffers and/or sound cards or
496 Like media stream objects, audio device objects are containers for the
497 underlying driver libraries.
499 @defun make-audio-device driver &rest device-options
500 Create a new device to output audio via @var{driver}.
501 @var{driver} should be a symbol out of 'oss, 'nas, 'esd, 'pulse,
502 'jack, 'alsa, 'arts or 'ao.
504 The rest arguments may be used to pass options to the selected
505 output driver. These should be `:keyword value' pairs.
507 Valid keywords for ALSA are:
508 :device - the name of the hardware interface (default: "default"),
509 you may want to try "plughw:0,0" first
510 :keep-open - whether to exclusively reserve the device.
511 Note this may prevent other applications from using the device.
513 Valid keywords for (deprecated) OSS are:
514 :device - the name of the hardware interface (default: "/dev/dsp")
515 :keep-open - whether to exclusively reserve the device.
516 Note this may prevent other applications from using the device.
518 Valid keywords for ESD are:
519 :server - to use a distant ESD daemon (e.g. "my.machine.box:16001")
520 The default for ESD output is to use a locally running daemon and
521 to connect to it via unix domain sockets.
523 Valid keywords for Pulse are:
524 :server - the host name to connect to (default: "localhost")
525 :sink - the name of the sink to connect to (e.g. "output")
526 :source - the name of the source to record from (e.g. "mic_in")
527 :client - how to call the client on the server (default "SXEmacs")
528 :stream - how to call the stream on the server (e.g. "fancy-sound")
529 :immediate - connect to sink immediately and keep the connection
530 alive as long as the audio device exists (default `t')
531 :threaded - initiate a threaded mainloop (default `t')
532 :force - if non-`nil' the device object is created even though the
533 pulse mainloop could not be started; if `nil' any mainloop failure
534 results in an error. This can be useful if you want to have an
535 audio device object although the server is not (yet) up or not
536 (yet) accepting connections from you. (default `nil')
538 Valid keywords for Jack are:
539 :server - the jack server to connect to (default "default")
540 :client - how to call the client on the server (default "SXEmacs")
542 Valid keywords for AO are:
543 :driver - the name of the output driver (e.g. "alsa", "esd", etc.)
544 :options - a list of AO suboptions (see AO documentation)
545 The default for AO output is to pass nothing and entirely use the
546 system and user configuration files.
548 Valid keywords for NAS are:
549 :server - the NAS server to connect to. This can be either:
550 - an X display string like "localhost:0.0", the X display string
551 the current frame is on can be obtained by the function
553 - or a SXEmacs device name like "localhost-11-0" which can be
554 obtained by `device-name'
555 - or a SXEmacs device object, obtainable by `frame-device', like
556 #<x-device on "localhost:11.0" 0xee4>
557 If the :server keyword is omitted SXEmacs tries to determine a
558 sensible default in this order:
559 - use the frame device of the current frame
560 - use the frame device of the initial frame
561 - use the display specified in $AUDIOSERVER
562 - use the display specified in $DISPLAY
563 - try "localhost:0.0"
565 Valid keywords for aRts are:
571 (make-audio-device 'pulse)
572 @result{} #<audio-device :type pulse :server #default :sink #default
573 :source #default :server-state #connected :api #threaded
574 :mainloop 0x973f8c0 :device-state #unknown>
578 (make-audio-device 'jack)
579 @result{} #<audio-device :type jack :server #default :client SXEmacs
580 :device-state #unknown>
584 @defun audio-device-p object
585 Return non-@code{nil} if @var{object} is an audio-device, @code{nil}
589 @defvar default-audio-device nil
590 Default audio device to use.
595 @section Media Threads
597 Media threads can be thought of a way to plug a certain media stream
598 into a certain output device. Since SXEmacs merely supports audio
599 output devices the only partition which is finally ``played'' is an
602 @c This changeset completely splits up the Thread and Stream types into trees. This
603 @c allows to have several substreams embedded into a stream, respectively several
604 @c subthreads can be started from a thread.
606 The current structure looks like:
610 +------------> Stream <------------+
614 substream1 <-----> substream2 <-----> substream3
618 Similarly for Threads:
622 +------------> Thread <------------+
626 subthread1 <-----> subthread2 <-----> subthread3
631 To be precise, threads are the containers for the streams. Streams are stored
632 (along with devices) inside threads, while substreams are stored inside
633 subthreads. In source/sink language, a thread is the cable to plug a source
634 (stream) to a sink (device).
640 ,-----> | Thread | <-----,
651 +==========+ next +==========+ next +==========+
652 |subthread1| <-----> |subthread2| <-----> |subthread3|
653 +----------+ prev +----------+ prev +----------+
654 |substream1| |substream2| |substream3|
655 |pthread_t1| |pthread_t2| |pthread_t3|
656 |privdata1 | |privdata2 | |privdata3 |
657 +==========+ +==========+ +==========+
660 Note: It is yet @emph{not} possible to specify different devices for
661 each subthread. This will require another split of the device
662 structure into a device+subdevice tree.
664 In order to actually plug a media stream to an audio device you first
665 have to decide whether you want the safe synchronous, or the
666 experimental asynchronous way.
668 Due to the experimental status of asynchronous playback it has to be
669 turned on explicitly.
671 @defvar number-of-media-workers 4
672 Number of worker threads spawned as queue listeners.
675 @defun init-asynchronousity
676 Initialise queue listener threads.
677 The number of spawned worker threads can be controlled by
678 @code{number-of-media-workers}.
679 When called the complementary variable @code{synchronous-sounds} is
683 @defun uninit-asynchronousity
684 Stop all queue listener threads.
685 Depending on whether there are busy threads this may block the
686 main execution loop until all worker threads are non-busy.
687 When called the complementary variable @code{synchronous-sounds} is
691 @defun play-media-stream-synchronously stream &optional device sentinel volume
692 Play the media stream @var{stream} on an audio device synchronously.
693 This function disregards the value of @code{synchronous-sounds},
694 instead streams will always be played in synchronous mode.
696 Optional second argument @var{device} must be an audio device created
697 by @code{make-audio-device}.
698 If omitted @var{device} defaults to the value of
699 @code{default-audio-device}.
701 Optional third argument @var{sentinel} specifies a lisp function to be
702 called after the stream playback finishes. The function should
703 take one argument (@var{stream}) where @var{stream} is bound to the
704 media stream which finished. See @code{set-media-thread-sentinel}.
706 Optional fourth argument @code{volume} specifies an initial value for
710 @defun play-media-stream-asynchronously stream &optional device sentinel volume
711 Play the media stream @var{stream} on an audio device asynchronously.
712 Return a media-thread object which can be used to interact with
713 the worker thread which handles @var{stream}.
714 This function disregards the value of @code{synchronous-sounds},
715 instead streams will always be played in asynchronous mode,
716 provided the worker threads have been initialised.
717 See @code{init-asynchronousity}.
719 Optional second argument @var{device} must be an audio device created
720 by @code{make-audio-device}.
721 If omitted @code{device} defaults to the value of
722 @code{default-audio-device}.
724 Optional third argument @var{sentinel} specifies a lisp function to be
725 called after the stream playback finishes. The function should
726 take one argument (@var{stream}) where @var{stream} is bound to the
727 media stream which finished. See @code{set-media-thread-sentinel}.
729 Optional fourth argument @code{volume} specifies an initial value for
733 To overcome the problem of deciding which of the playback functions to
734 use, there is a wrapper function which does The Right Thing@sc{[tm]}.
736 @defvar synchronous-sounds t
737 Play sounds synchronously, if non-@code{nil}.
738 Only applies if SXEmacs has been compiled with a threading library.
739 Otherwise, sounds are always played synchronously.
742 @defun play-media-stream stream &optional device sentinel volume
743 Play the media stream @var{stream} on an audio device.
744 @var{stream} must be a valid media-stream object as created by
745 @code{make-media-stream}.
747 Optional second argument @var{device} must be an audio device created
748 by @code{make-audio-device}.
749 If omitted @var{device} defaults to the value of
750 @code{default-audio-device}.
752 Optional third argument @var{sentinel} specifies a lisp function to be
753 called after the stream playback finishes. The function should
754 take one argument (@var{stream}) where @var{stream} is bound to the
755 media stream which finished. See @code{set-media-thread-sentinel}.
757 Optional fourth argument @var{volume} specifies an initial value for
761 Depending on the value of @code{synchronous-sounds} this function will
762 decide whether to play either asynchronously or synchronously.
764 If @code{synchronous-sounds} is @code{nil} @emph{and} threads are
765 supported, streams will be passed to the
766 @code{play-media-stream-asynchronously} function.
767 In that case return a media-thread object which can be used to
768 interact with the worker thread which handles @var{stream}.
770 If @code{synchronous-sounds} is non-@code{nil} @emph{or} threads are
771 not supported, streams will be passed to the
772 @code{play-media-stream-synchronously} function.
773 In that case return non-@code{nil} if @var{stream} was played
774 successfully, and @code{nil} otherwise.
776 See @code{play-media-stream-synchronously} and
777 @code{play-media-stream-asynchronously}."
781 @defun pause-media-thread thread
782 Pause the media thread @var{thread}.
783 Optionally @var{thread} can be @code{'all} in which case all running
784 media threads are paused.
787 @defun resume-media-thread thread
788 Resume a paused media thread @var{thread}.
789 Optionally @var{thread} can be @code{'all} in which case all paused
790 media threads are resumed.
793 @defun stop-media-thread thread
794 Stop a media thread @var{thread}.
795 Optionally @var{thread} can be @code{'all} in which case all media
798 Stopping @var{thread} will unleash the respective worker threads.
799 This is an irreversible action.
802 @defun media-thread-set-volume thread volume
803 Set the volume of the media thread @var{thread} to @var{volume}.
805 @var{thread} is a media thread object with an audio substream.
806 Optionally @var{thread} can be @code{'all} in which case the volume
807 change applies to all media threads.
809 @var{volume} is either a comparable number (see @code{comparablep}) or
810 a vector of comparable numbers.
811 In the former case @var{volume} sets the master volume of all channels.
812 In the latter case @var{volume} sets the volumes channelwise.
814 Any volume value is coerced to an integer.
815 A volume of 128 is the norm.
816 A volume of 0 is muting the respective channels.
817 A volume of 255 is the maximal volume, though clipping may occur.
818 Volumes greater than 128 cause an amplification of the stream,
819 255 is the maximal value. Note that clipping may occur.
822 @defun media-thread-volume thread
823 Return the current volume of media thread @var{thread}.
826 @defun media-thread-set-rate thread rate
827 Set the rate of media thread @var{thread} to @var{rate}.
829 @var{thread} is a media thread object with an audio or video
830 substream. Optionally @var{thread} can be @code{'all} in which case
831 the rate change applies to all media threads.
834 @defun media-thread-rate thread
835 Return the current rate of media thread @var{thread}.
839 @defun ding &optional arg sound device
840 Beep, or flash the frame.
841 Also, unless an argument is given,
842 terminate any keyboard macro currently executing.
843 When called from lisp, the second argument is what sound to make, and
844 the third argument is the device to make it in (defaults to the selected
845 device), but may also be an audio device created by
846 @code{make-audio-device}.
850 @c sounds by symbol voodoo
852 @defvar sound-alist nil
853 An alist associating names with sounds.
854 When @code{beep} or @code{ding} is called with one of the name
855 symbols, the associated sound will be generated instead of the
858 Each element of @code{sound-alist} is a list describing a sound.
859 The first element of the list is the name of the sound being defined.
860 Subsequent elements of the list are alternating keyword/value pairs:
864 sound A string of raw sound data (deprecated), or the name of another
865 sound to play. The symbol @code{t} here means use the
867 stream A media stream object containing the sound.
868 volume An integer from 0-255, defaulting to @code{bell-volume}
869 pitch If using the default X beep, the pitch (Hz) to generate.
870 duration If using the default X beep, the duration (milliseconds).
872 You should probably add things to this list by calling the function
873 @code{load-sound-file}.
875 Note: SXEmacs must be built with sound support for your system. Not all
876 systems support sound.
877 Note: The pitch, duration, and volume options are available everywhere,
878 but many X servers ignore the @code{pitch} option.
880 The following beep-types are used by SXEmacs itself:
882 auto-save-error when an auto-save does not succeed
883 command-error when the emacs command loop catches an error
884 undefined-key when you type a key that is undefined
885 undefined-click when you use an undefined mouse-click combination
886 no-completion during completing-read
887 y-or-n-p when you type something other than `y' or `n'
888 yes-or-no-p when you type something other than `yes' or `no'
889 default used when nothing else is appropriate.
891 Other lisp packages may use other beep types, but these are the ones that
892 the C kernel of Emacs uses.
895 @c moved from display.texi
896 @defun play-sound sound &optional volume device sentinel
897 Play the sound @var{sound} (a symbol) from @var{sound-alist}.
899 The sound is played at the specified @var{volume} (0-100, default
900 specified by the @var{bell-volume} variable).
902 With no further media drivers, the sound file must be in the
903 Sun/NeXT U-LAW format. Under Linux WAV files are also supported.
905 @var{device} can be any device created by @code{make-audio-device}
906 and defaults to @var{default-audio-device}, or, if that is @code{nil},
907 to the selected device.
909 Optional argument @var{sentinel} specifies a lisp function to be
910 called after the stream playback finishes. The function should
911 take two arguments (@var{stream} @var{state}) where @var{stream}
912 is bound to the media stream which finished and @var{state} is a
913 symbol (currently the only valid symbol is @code{'finished}).
914 See @code{set-media-thread-sentinel}.
917 @defun load-sound-file filename sound-name &optional volume
918 Read in an audio-file and add it to the sound-alist.
919 The cached sound can be referenced later by @var{sound-name}.
921 @var{filename} can either be absolute or relative, in which case the
922 file will be searched in the directories given by
923 @code{default-sound-directory-list}.
924 When looking for the file, the extensions given by
925 @code{sound-extension-list} are also tried in the given order.
929 @c @c @c media.texi ends here