aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
diff options
context:
space:
mode:
authorGabor Kovesdan <gabor@FreeBSD.org>2012-10-01 09:53:01 +0000
committerGabor Kovesdan <gabor@FreeBSD.org>2012-10-01 09:53:01 +0000
commitb4346b9b2dfe86a97907573086dff096850dcb1d (patch)
tree9b951977cbd22dada9b868ac83b1d56791ea3859 /en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
parentbee5d224febbeba11356aa848006a4f5f9e24b30 (diff)
downloaddoc-b4346b9b2dfe86a97907573086dff096850dcb1d.tar.gz
doc-b4346b9b2dfe86a97907573086dff096850dcb1d.zip
- Rename .sgml files to .xml
- Reflect the rename in referencing files Approved by: doceng (implicit)
Notes
Notes: svn path=/head/; revision=39631
Diffstat (limited to 'en_US.ISO8859-1/books/handbook/multimedia/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/handbook/multimedia/chapter.xml1938
1 files changed, 1938 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
new file mode 100644
index 0000000000..6856ac9abe
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
@@ -0,0 +1,1938 @@
+<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
+<!--
+ The FreeBSD Documentation Project
+
+ $FreeBSD$
+-->
+
+<chapter id="multimedia">
+ <chapterinfo>
+ <authorgroup>
+ <author>
+ <firstname>Ross</firstname>
+ <surname>Lippert</surname>
+ <contrib>Edited by </contrib>
+ </author>
+ </authorgroup>
+ </chapterinfo>
+
+ <title>Multimedia</title>
+ <sect1 id="multimedia-synopsis">
+ <title>Synopsis</title>
+
+ <para>FreeBSD supports a wide variety of sound cards, allowing you
+ to enjoy high fidelity output from your computer. This includes
+ the ability to record and playback audio in the MPEG Audio Layer
+ 3 (MP3), WAV, and Ogg Vorbis formats as well as many other
+ formats. The FreeBSD Ports Collection also contains
+ applications allowing you to edit your recorded audio, add sound
+ effects, and control attached MIDI devices.</para>
+
+ <para>With some experimentation, &os; can support
+ playback of video files and DVDs. The number of applications
+ to encode, convert, and playback various video media is more
+ limited than the number of sound applications. For example as
+ of this writing, there are no good re-encoding applications in the
+ FreeBSD Ports Collection that could be used to convert
+ between formats, as there is with <filename
+ role="package">audio/sox</filename>. However, the software
+ landscape in this area is changing rapidly.</para>
+
+ <para>This chapter will describe the necessary steps to configure
+ your sound card. The configuration and installation of X11
+ (<xref linkend="x11"/>) has already taken care of the
+ hardware issues for your video card, though there may be some
+ tweaks to apply for better playback.</para>
+
+ <para>After reading this chapter, you will know:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>How to configure your system so that your sound card is
+ recognized.</para>
+ </listitem>
+
+ <listitem>
+ <para>Methods to test whether your card is working.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to troubleshoot your sound setup.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to playback and encode MP3s and other audio.</para>
+ </listitem>
+
+ <listitem>
+ <para>How video is supported by the X server.</para>
+ </listitem>
+
+ <listitem>
+ <para>Some video player/encoder ports which give good results.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to playback DVDs, <filename>.mpg</filename> and
+ <filename>.avi</filename> files.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to rip CD and DVD content into files.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to configure a TV card.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to configure an image scanner.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Before reading this chapter, you should:</para>
+
+ <itemizedlist>
+ <listitem><para>Know how to configure and install a new kernel (<xref
+ linkend="kernelconfig"/>).</para></listitem>
+ </itemizedlist>
+
+ <warning>
+ <para>Trying to mount audio CDs
+ with the &man.mount.8; command will
+ result in an error, at least, and a <emphasis>kernel
+ panic</emphasis>, at worst. These media have specialized
+ encodings which differ from the usual ISO-filesystem.</para>
+ </warning>
+
+ </sect1>
+
+ <sect1 id="sound-setup">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Moses</firstname>
+ <surname>Moore</surname>
+ <contrib>Contributed by </contrib>
+ <!-- 20 November 2000 -->
+ </author>
+ </authorgroup>
+ <authorgroup>
+ <author>
+ <firstname>Marc</firstname>
+ <surname>Fonvieille</surname>
+ <contrib>Enhanced by </contrib>
+ <!-- 13 September 2004 -->
+ </author>
+ </authorgroup>
+ </sect1info>
+
+ <title>Setting Up the Sound Card</title>
+
+ <sect2 id="sound-device">
+ <title>Configuring the System</title>
+
+ <indexterm><primary>PCI</primary></indexterm>
+ <indexterm><primary>ISA</primary></indexterm>
+ <indexterm><primary>sound cards</primary></indexterm>
+ <para>Before you begin, you should know the model of the card you
+ have, the chip it uses, and whether it is a PCI or ISA card.
+ FreeBSD supports a wide variety of both PCI and ISA cards.
+ Check the supported audio devices list of the <ulink
+ url="&rel.current.hardware;">Hardware Notes</ulink> to see if
+ your card is supported. The Hardware Notes will also mention which
+ driver supports your card.</para>
+
+ <indexterm>
+ <primary>kernel</primary>
+ <secondary>configuration</secondary>
+ </indexterm>
+
+ <para>To use your sound device, you will need to load the proper
+ device driver. This may be accomplished in one of two ways.
+ The easiest way is to simply load a kernel module for your sound
+ card with &man.kldload.8; which can either be done from the
+ command line:</para>
+
+ <screen>&prompt.root; <userinput>kldload snd_emu10k1</userinput></screen>
+
+ <para>or by adding the appropriate line to the file
+ <filename>/boot/loader.conf</filename> like this:</para>
+
+ <programlisting>snd_emu10k1_load="YES"</programlisting>
+
+ <para>These examples are for a Creative &soundblaster; Live! sound
+ card. Other available loadable sound modules are listed in
+ <filename>/boot/defaults/loader.conf</filename>.
+ If you are not sure which driver to use, you may try to load
+ the <filename>snd_driver</filename> module:</para>
+
+ <screen>&prompt.root; <userinput>kldload snd_driver</userinput></screen>
+
+ <para>This is a metadriver loading the most common device drivers
+ at once. This speeds up the search for the correct driver. It
+ is also possible to load all sound drivers via the
+ <filename>/boot/loader.conf</filename> facility.</para>
+
+ <para>If you wish to find out the driver selected for your
+ soundcard after loading the <filename>snd_driver</filename>
+ metadriver, you may check the <filename>/dev/sndstat</filename>
+ file with the <command>cat /dev/sndstat</command>
+ command.</para>
+
+ <para>A second method is to statically
+ compile in support for your sound card in your kernel. The
+ section below provides the information you need to add support
+ for your hardware in this manner. For more information about
+ recompiling your kernel, please see <xref
+ linkend="kernelconfig"/>.</para>
+
+ <sect3>
+ <title>Configuring a Custom Kernel with Sound Support</title>
+
+ <para>The first thing to do is add the audio framework driver
+ &man.sound.4; to the kernel; for that you will need to
+ add the following line to the kernel configuration file:</para>
+
+ <programlisting>device sound</programlisting>
+
+ <para>Next, you have to add the support for your sound card.
+ Therefore, you need to know which driver supports the card.
+ Check the supported audio devices list of the <ulink
+ url="&rel.current.hardware;">Hardware Notes</ulink>, to
+ determine the correct driver for your sound card. For
+ example, a Creative &soundblaster; Live! sound card is
+ supported by the &man.snd.emu10k1.4; driver. To add the support
+ for this card, use the following:</para>
+
+ <programlisting>device snd_emu10k1</programlisting>
+
+ <para>Be sure to read the manual page of the driver for the
+ syntax to use. The explicit syntax for the kernel configuration
+ of every supported sound driver can also be found in the
+ <filename>/usr/src/sys/conf/NOTES</filename> file.</para>
+
+ <para>Non-PnP ISA sound cards may require you to provide the kernel
+ with information on the card settings (IRQ, I/O port,
+ etc), as is true of all non-PnP ISA cards. This is done via the
+ <filename>/boot/device.hints</filename> file. During the boot process,
+ the &man.loader.8; will read this file and pass the settings
+ to the kernel. For example, an old
+ Creative &soundblaster; 16 ISA non-PnP card will use the
+ &man.snd.sbc.4; driver in conjunction with <literal>snd_sb16</literal>. For this card the following lines must be added to
+ the kernel configuration file:</para>
+
+ <programlisting>device snd_sbc
+device snd_sb16</programlisting>
+
+ <para>and these to
+ <filename>/boot/device.hints</filename>:</para>
+
+ <programlisting>hint.sbc.0.at="isa"
+hint.sbc.0.port="0x220"
+hint.sbc.0.irq="5"
+hint.sbc.0.drq="1"
+hint.sbc.0.flags="0x15"</programlisting>
+
+ <para>In this case, the card uses the <literal>0x220</literal>
+ I/O port and the IRQ <literal>5</literal>.</para>
+
+ <para>The syntax used in the
+ <filename>/boot/device.hints</filename> file is covered in the
+ &man.sound.4; driver manual page and the manual page
+ for the driver in question.</para>
+
+ <para>The settings shown above are the defaults. In some
+ cases, you may need to change the IRQ or the other settings to
+ match your card. See the &man.snd.sbc.4; manual page for more
+ information about this card.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="sound-testing">
+ <title>Testing the Sound Card</title>
+
+ <para>After rebooting with the modified kernel, or after loading
+ the required module, the sound card should appear in your system
+ message buffer (&man.dmesg.8;) as something like:</para>
+
+ <screen>pcm0: &lt;Intel ICH3 (82801CA)&gt; port 0xdc80-0xdcbf,0xd800-0xd8ff irq 5 at device 31.5 on pci0
+pcm0: [GIANT-LOCKED]
+pcm0: &lt;Cirrus Logic CS4205 AC97 Codec&gt;</screen>
+
+ <para>The status of the sound card may be checked via the
+ <filename>/dev/sndstat</filename> file:</para>
+
+ <screen>&prompt.root; <userinput>cat /dev/sndstat</userinput>
+FreeBSD Audio Driver (newpcm)
+Installed devices:
+pcm0: &lt;Intel ICH3 (82801CA)&gt; at io 0xd800, 0xdc80 irq 5 bufsz 16384
+kld snd_ich (1p/2r/0v channels duplex default)</screen>
+
+ <para>The output from your system may vary. If no
+ <devicename>pcm</devicename> devices are listed, go back and review
+ what was done earlier. Go through your kernel
+ configuration file again and make sure the correct
+ device driver was chosen. Common problems are listed in <xref
+ linkend="troubleshooting"/>.</para>
+
+ <para>If all goes well, you should now have a functioning sound
+ card. If your CD-ROM or DVD-ROM drive's audio-out pins are properly connected to
+ your sound card, you can put a CD in the drive and play it
+ with &man.cdcontrol.1;:</para>
+
+ <screen>&prompt.user; <userinput>cdcontrol -f /dev/acd0 play 1</userinput></screen>
+
+ <para>Various applications, such as <filename
+ role="package">audio/workman</filename> can provide a friendlier
+ interface. You may want to install an application such as
+ <filename role="package">audio/mpg123</filename> to listen to
+ MP3 audio files.</para>
+
+ <para>Another quick way to test the card is sending data
+ to <filename>/dev/dsp</filename>, like this:</para>
+
+ <screen>&prompt.user; <userinput>cat <replaceable>filename</replaceable> &gt; /dev/dsp</userinput></screen>
+
+ <para>where <filename><replaceable>filename</replaceable></filename> can be any file.
+ This command line should produce some noise, confirming the
+ sound card is actually working.</para>
+
+ <note>
+ <para>The device nodes <filename>/dev/dsp*</filename> will be
+ created automatically when needed. If they are not used, they
+ do not exist and will not appear in the output of
+ &man.ls.1;.</para>
+ </note>
+
+ <para>Sound card mixer levels can be changed via the &man.mixer.8;
+ command. More details can be found in the &man.mixer.8; manual
+ page.</para>
+
+ <sect3 id="troubleshooting">
+ <title>Common Problems</title>
+
+ <indexterm><primary>device nodes</primary></indexterm>
+ <indexterm><primary>I/O port</primary></indexterm>
+ <indexterm><primary>IRQ</primary></indexterm>
+ <indexterm><primary>DSP</primary></indexterm>
+
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Error</entry>
+ <entry>Solution</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><errorname>sb_dspwr(XX) timed out</errorname></entry>
+ <entry><para>The I/O port is not set correctly.</para></entry>
+ </row>
+
+ <row>
+ <entry><errorname>bad irq XX</errorname></entry>
+ <entry><para>The IRQ is set incorrectly. Make sure that
+ the set IRQ and the sound IRQ are the same.</para></entry>
+ </row>
+
+ <row>
+ <entry><errorname>xxx: gus pcm not attached, out of memory</errorname></entry>
+ <entry><para>There is not enough available memory to use
+ the device.</para></entry>
+ </row>
+
+ <row>
+ <entry><errorname>xxx: can't open /dev/dsp!</errorname></entry>
+ <entry><para>Check with <command>fstat | grep dsp</command>
+ if another application is holding the device open.
+ Noteworthy troublemakers are <application>esound</application> and <application>KDE</application>'s sound
+ support.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>Another issue is that modern graphics cards often come with their
+ own sound driver, for use with <acronym>HDMI</acronym> and similar.
+ This sound device will sometimes be enumerated before the actual
+ soundcard and the soundcard will subsequently not be used as the
+ default playback device. To check if this is the case, run
+ <application>dmesg</application> and look for <literal>pcm</literal>.
+ The output looks something like this:</para>
+
+<programlisting>...
+hdac0: HDA Driver Revision: 20100226_0142
+hdac1: HDA Driver Revision: 20100226_0142
+hdac0: HDA Codec #0: NVidia (Unknown)
+hdac0: HDA Codec #1: NVidia (Unknown)
+hdac0: HDA Codec #2: NVidia (Unknown)
+hdac0: HDA Codec #3: NVidia (Unknown)
+pcm0: &lt;HDA NVidia (Unknown) PCM #0 DisplayPort&gt; at cad 0 nid 1 on hdac0
+pcm1: &lt;HDA NVidia (Unknown) PCM #0 DisplayPort&gt; at cad 1 nid 1 on hdac0
+pcm2: &lt;HDA NVidia (Unknown) PCM #0 DisplayPort&gt; at cad 2 nid 1 on hdac0
+pcm3: &lt;HDA NVidia (Unknown) PCM #0 DisplayPort&gt; at cad 3 nid 1 on hdac0
+hdac1: HDA Codec #2: Realtek ALC889
+pcm4: &lt;HDA Realtek ALC889 PCM #0 Analog&gt; at cad 2 nid 1 on hdac1
+pcm5: &lt;HDA Realtek ALC889 PCM #1 Analog&gt; at cad 2 nid 1 on hdac1
+pcm6: &lt;HDA Realtek ALC889 PCM #2 Digital&gt; at cad 2 nid 1 on hdac1
+pcm7: &lt;HDA Realtek ALC889 PCM #3 Digital&gt; at cad 2 nid 1 on hdac1
+...</programlisting>
+
+ <para>Here the graphics card (<literal>NVidia</literal>) has been
+ enumerated before the sound card (<literal>Realtek ALC889</literal>).
+ To use the sound card as default playback device, change
+ <literal>hw.snd.default_unit</literal> to the unit that should be used
+ for playback, enter the following:</para>
+
+ <screen>&prompt.root; <userinput>sysctl hw.snd.default_unit=<replaceable>n</replaceable></userinput></screen>
+
+ <para>Here, <literal>n</literal> is the number of the sound device to
+ use, in this example <literal>4</literal>. You can make this change
+ permanent by adding the following line to
+ <filename>/etc/sysctl.conf</filename>:</para>
+
+ <programlisting>hw.snd.default_unit=<replaceable>4</replaceable></programlisting>
+ </sect3>
+ </sect2>
+
+ <sect2 id="sound-multiple-sources">
+ <sect2info>
+ <authorgroup>
+ <author>
+ <firstname>Munish</firstname>
+ <surname>Chopra</surname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ </sect2info>
+ <title>Utilizing Multiple Sound Sources</title>
+
+ <para>It is often desirable to have multiple sources of sound that
+ are able to play simultaneously, such as when
+ <application>esound</application> or
+ <application>artsd</application> do not support sharing of the
+ sound device with a certain application.</para>
+
+ <para>FreeBSD lets you do this through <emphasis>Virtual Sound
+ Channels</emphasis>, which can be enabled with the &man.sysctl.8;
+ facility. Virtual channels allow you to multiplex your sound
+ card's playback by mixing sound in the kernel.</para>
+
+ <para>To set the number of virtual channels, there are three sysctl
+ knobs which, if you are the <username>root</username> user, can
+ be set like this:</para>
+ <screen>&prompt.root; <userinput>sysctl dev.pcm.0.play.vchans=4</userinput>
+&prompt.root; <userinput>sysctl dev.pcm.0.rec.vchans=4</userinput>
+&prompt.root; <userinput>sysctl hw.snd.maxautovchans=4</userinput></screen>
+
+ <para>The above example allocates four virtual channels, which is a
+ practical number for everyday use. Both <varname>dev.pcm.0.play.vchans=4</varname>
+ and <varname>dev.pcm.0.rec.vchans=4</varname>
+ are the number of virtual channels <devicename>pcm0</devicename> has for playback and recording, and are configurable
+ once a device has been attached.
+ <literal>hw.snd.maxautovchans</literal> is the number of virtual channels
+ a new audio device is given when it is attached using
+ &man.kldload.8;. Since the <devicename>pcm</devicename> module
+ can be loaded independently of the hardware drivers,
+ <varname>hw.snd.maxautovchans</varname> can store how many
+ virtual channels any devices which are attached later will be
+ given. Refer to &man.pcm.4; manual page for more
+ information.</para>
+
+ <note>
+ <para>You cannot change the number of virtual channels for a
+ device while it is in use. First close any programs using the
+ device, such as music players or sound daemons.</para>
+ </note>
+
+ <para>
+ The correct <devicename>pcm</devicename> device will
+ automatically be allocated transparently to a program
+ that requests <filename>/dev/dsp0</filename>.</para>
+ </sect2>
+
+ <sect2>
+ <sect2info>
+ <authorgroup>
+ <author>
+ <firstname>Josef</firstname>
+ <surname>El-Rayes</surname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ </sect2info>
+
+ <title>Setting Default Values for Mixer Channels</title>
+
+ <para>The default values for the different mixer channels are
+ hardcoded in the sourcecode of the &man.pcm.4; driver. There are
+ many different applications and daemons that allow
+ you to set values for the mixer that are remembered between
+ invocations, but this is not a clean solution. It is possible
+ to set default mixer values at the driver level &mdash; this
+ is accomplished by defining the appropriate
+ values in <filename>/boot/device.hints</filename>, e.g.:</para>
+
+<programlisting>hint.pcm.0.vol="50"</programlisting>
+
+ <para>This will set the volume channel to a default value of
+ 50 when the &man.pcm.4; module is loaded.</para>
+ </sect2>
+</sect1>
+
+ <sect1 id="sound-mp3">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Chern</firstname>
+ <surname>Lee</surname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ <!-- 11 Sept 2001 -->
+ </sect1info>
+
+ <title>MP3 Audio</title>
+
+ <para>MP3 (MPEG Layer 3 Audio) accomplishes near CD-quality sound,
+ leaving no reason to let your FreeBSD workstation fall short of
+ its offerings.</para>
+
+ <sect2 id="mp3-players">
+ <title>MP3 Players</title>
+
+ <para>By far, the most popular X11 MP3 player is
+ <application>XMMS</application> (X Multimedia System).
+ <application>Winamp</application>
+ skins can be used with <application>XMMS</application> since the
+ GUI is almost identical to that of Nullsoft's
+ <application>Winamp</application>.
+ <application>XMMS</application> also has native plug-in
+ support.</para>
+
+ <para><application>XMMS</application> can be installed from the
+ <filename role="package">multimedia/xmms</filename> port or package.</para>
+
+ <para><application>XMMS</application>'s interface is intuitive,
+ with a playlist, graphic equalizer, and more. Those familiar
+ with <application>Winamp</application> will find
+ <application>XMMS</application> simple to use.</para>
+
+ <para>The <filename role="package">audio/mpg123</filename> port is an alternative,
+ command-line MP3 player.</para>
+
+ <para><application>mpg123</application> can be run by specifying
+ the sound device and the MP3 file on the command line. Assuming your
+ audio device is <devicename>/dev/dsp1.0</devicename> and you want
+ to play the MP3 file <replaceable>Foobar-GreatestHits.mp3</replaceable>
+ you would enter the following:</para>
+
+ <screen>&prompt.root; <userinput>mpg123 -a <devicename>/dev/dsp1.0</devicename> <replaceable>Foobar-GreatestHits.mp3</replaceable></userinput>
+High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3.
+Version 0.59r (1999/Jun/15). Written and copyrights by Michael Hipp.
+Uses code from various people. See 'README' for more!
+THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY! USE AT YOUR OWN RISK!
+
+
+
+
+
+Playing MPEG stream from Foobar-GreatestHits.mp3 ...
+MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo
+</screen>
+ </sect2>
+
+ <sect2 id="rip-cd">
+ <title>Ripping CD Audio Tracks</title>
+
+ <para>Before encoding a CD or CD track to MP3, the audio data on
+ the CD must be ripped onto the hard drive. This is done by
+ copying the raw CDDA (CD Digital Audio) data to WAV
+ files.</para>
+
+ <para>The <command>cdda2wav</command> tool, which is a part of
+ the <filename role="package">sysutils/cdrtools</filename>
+ suite, is used for ripping audio information from CDs and the
+ information associated with them.</para>
+
+ <para>With the audio CD in the drive, the following command can
+ be issued (as <username>root</username>) to rip an entire CD
+ into individual (per track) WAV files:</para>
+
+ <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -B</userinput></screen>
+
+ <para><application>cdda2wav</application> will support
+ ATAPI (IDE) CDROM drives. To rip from an IDE drive, specify
+ the device name in place of the SCSI unit numbers. For
+ example, to rip track 7 from an IDE drive:</para>
+
+ <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>/dev/acd0</replaceable> -t 7</userinput></screen>
+
+ <para>The <option>-D <replaceable>0,1,0</replaceable></option>
+ indicates the SCSI device <devicename>0,1,0</devicename>,
+ which corresponds to the output of <command>cdrecord
+ -scanbus</command>.</para>
+
+ <para>To rip individual tracks, make use of the
+ <option>-t</option> option as shown:</para>
+
+ <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 7</userinput></screen>
+
+ <para>This example rips track seven of the audio CDROM. To rip
+ a range of tracks, for example, track one to seven, specify a
+ range:</para>
+
+ <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 1+7</userinput></screen>
+
+ <para>The utility &man.dd.1; can also be used to extract audio tracks
+ on ATAPI drives, read <xref linkend="duplicating-audiocds"/>
+ for more information on that possibility.</para>
+
+ </sect2>
+
+ <sect2 id="mp3-encoding">
+ <title>Encoding MP3s</title>
+
+ <para>Nowadays, the mp3 encoder of choice is
+ <application>lame</application>.
+ <application>Lame</application> can be found at
+ <filename role="package">audio/lame</filename> in the ports tree.</para>
+
+ <para>Using the ripped WAV files, the following command will
+ convert <filename><replaceable>audio01.wav</replaceable></filename> to
+ <filename><replaceable>audio01.mp3</replaceable></filename>:</para>
+
+ <screen>&prompt.root; <userinput>lame -h -b <replaceable>128</replaceable> \
+--tt "<replaceable>Foo Song Title</replaceable>" \
+--ta "<replaceable>FooBar Artist</replaceable>" \
+--tl "<replaceable>FooBar Album</replaceable>" \
+--ty "<replaceable>2001</replaceable>" \
+--tc "<replaceable>Ripped and encoded by Foo</replaceable>" \
+--tg "<replaceable>Genre</replaceable>" \
+<replaceable>audio01.wav audio01.mp3</replaceable></userinput></screen>
+
+ <para>128&nbsp;kbits seems to be the standard MP3 bitrate in use.
+ Many enjoy the higher quality 160, or 192. The higher the
+ bitrate, the more disk space the resulting MP3 will
+ consume--but the quality will be higher. The
+ <option>-h</option> option turns on the <quote>higher quality
+ but a little slower</quote> mode. The options beginning with
+ <option>--t</option> indicate ID3 tags, which usually contain
+ song information, to be embedded within the MP3 file.
+ Additional encoding options can be found by consulting the
+ <application>lame</application> man page.</para>
+ </sect2>
+
+ <sect2 id="mp3-decoding">
+ <title>Decoding MP3s</title>
+
+ <para>In order to burn an audio CD from MP3s, they must be
+ converted to a non-compressed WAV format. Both
+ <application>XMMS</application> and
+ <application>mpg123</application> support the output of MP3 to
+ an uncompressed file format.</para>
+
+ <para>Writing to Disk in <application>XMMS</application>:</para>
+
+ <procedure>
+ <step>
+ <para>Launch <application>XMMS</application>.</para>
+ </step>
+
+ <step>
+ <para>Right-click on the window to bring up the
+ <application>XMMS</application> menu.</para>
+ </step>
+
+ <step>
+ <para>Select <literal>Preference</literal> under
+ <literal>Options</literal>.</para>
+ </step>
+
+ <step>
+ <para>Change the Output Plugin to <quote>Disk Writer
+ Plugin</quote>.</para>
+ </step>
+
+ <step>
+ <para>Press <literal>Configure</literal>.</para>
+ </step>
+
+ <step>
+ <para>Enter (or choose browse) a directory to write the
+ uncompressed files to.</para>
+ </step>
+
+ <step>
+ <para>Load the MP3 file into <application>XMMS</application>
+ as usual, with volume at 100% and EQ settings turned
+ off.</para>
+ </step>
+
+ <step>
+ <para>Press <literal>Play</literal> &mdash;
+ <application>XMMS</application> will appear as if it is
+ playing the MP3, but no music will be heard. It is
+ actually playing the MP3 to a file.</para>
+ </step>
+
+ <step>
+ <para>Be sure to set the default Output Plugin back to what
+ it was before in order to listen to MP3s again.</para>
+ </step>
+ </procedure>
+
+ <para>Writing to stdout in <application>mpg123</application>:</para>
+
+ <procedure>
+ <step>
+ <para>Run <command>mpg123 -s <replaceable>audio01.mp3</replaceable>
+ &gt; <replaceable>audio01.pcm</replaceable></command></para>
+ </step>
+ </procedure>
+
+ <para><application>XMMS</application> writes a file in the WAV
+ format, while <application>mpg123</application> converts the
+ MP3 into raw PCM audio data. Both of these formats can be
+ used with <application>cdrecord</application> to create audio CDs.
+ You have to use raw PCM with &man.burncd.8;.
+ If you use WAV files, you will notice a small tick sound at the
+ beginning of each track, this sound is the header of the WAV
+ file. You can simply remove the header of a WAV file with the
+ utility <application>SoX</application> (it can be installed from
+ the <filename role="package">audio/sox</filename> port or
+ package):</para>
+
+ <screen>&prompt.user; <userinput>sox -t wav -r 44100 -s -w -c 2 <replaceable>track.wav track.raw</replaceable></userinput></screen>
+
+ <para>Read <xref linkend="creating-cds"/> for more information on using a
+ CD burner in FreeBSD.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="video-playback">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Ross</firstname>
+ <surname>Lippert</surname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ <!-- 5 June 2002 -->
+ </sect1info>
+
+ <title>Video Playback</title>
+
+ <para>Video playback is a very new and rapidly developing application
+ area. Be patient. Not everything is going to work as smoothly as
+ it did with sound.</para>
+
+ <para>Before you begin, you should know the model of the video
+ card you have and the chip it uses. While <application>&xorg;</application> supports a
+ wide variety of video cards, fewer give good playback
+ performance. To obtain a list of extensions supported by the
+ X server using your card use the command &man.xdpyinfo.1; while
+ X11 is running.</para>
+
+ <para>It is a good idea to have a short MPEG file which can be
+ treated as a test file for evaluating various players and
+ options. Since some DVD players will look for DVD media in
+ <filename>/dev/dvd</filename> by default, or have this device
+ name hardcoded in them, you might find it useful to make
+ symbolic links to the proper devices:</para>
+
+ <screen>&prompt.root; <userinput>ln -sf /dev/acd0 /dev/dvd</userinput>
+&prompt.root; <userinput>ln -sf /dev/acd0 /dev/rdvd</userinput></screen>
+
+ <para>Note that due to the nature of &man.devfs.5;,
+ manually created links like these will not persist if you reboot
+ your system. In order to create the symbolic links
+ automatically whenever you boot your system, add the following
+ lines to <filename>/etc/devfs.conf</filename>:</para>
+
+ <programlisting>link acd0 dvd
+link acd0 rdvd</programlisting>
+
+ <para>Additionally, DVD decryption, which requires invoking
+ special DVD-ROM functions, requires write permission on the DVD
+ devices.</para>
+
+ <para>To enhance the shared memory X11 interface, it is
+ recommended that the values of some &man.sysctl.8; variables
+ should be increased:</para>
+
+ <programlisting>kern.ipc.shmmax=67108864
+kern.ipc.shmall=32768</programlisting>
+
+ <sect2 id="video-interface">
+ <title>Determining Video Capabilities</title>
+
+ <indexterm><primary>XVideo</primary></indexterm>
+ <indexterm><primary>SDL</primary></indexterm>
+ <indexterm><primary>DGA</primary></indexterm>
+
+ <para>There are several possible ways to display video under X11.
+ What will really work is largely hardware dependent. Each
+ method described below will have varying quality across
+ different hardware. Secondly, the rendering of video in X11 is
+ a topic receiving a lot of attention lately, and with each
+ version of <application>&xorg;</application>, there may be significant improvement.</para>
+
+ <para>A list of common video interfaces:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>X11: normal X11 output using shared memory.</para>
+ </listitem>
+ <listitem>
+ <para>XVideo: an extension to the X11
+ interface which supports video in any X11 drawable.</para>
+ </listitem>
+ <listitem>
+ <para>SDL: the Simple Directmedia Layer.</para>
+ </listitem>
+ <listitem>
+ <para>DGA: the Direct Graphics Access.</para>
+ </listitem>
+ <listitem>
+ <para>SVGAlib: low level console graphics layer.</para>
+ </listitem>
+ </orderedlist>
+
+ <sect3 id="video-interface-xvideo">
+ <title>XVideo</title>
+
+ <para><application>&xorg;</application> has an extension called
+ <emphasis>XVideo</emphasis> (aka Xvideo, aka Xv, aka xv) which
+ allows video to be directly displayed in drawable objects
+ through a special acceleration. This extension provides very
+ good quality playback even on low-end machines.</para>
+
+ <para>To check whether the extension is running,
+ use <command>xvinfo</command>:</para>
+
+ <screen>&prompt.user; <userinput>xvinfo</userinput></screen>
+
+ <para>XVideo is supported for your card if the result looks like:</para>
+<screen>X-Video Extension version 2.2
+screen #0
+ Adaptor #0: "Savage Streams Engine"
+ number of ports: 1
+ port base: 43
+ operations supported: PutImage
+ supported visuals:
+ depth 16, visualID 0x22
+ depth 16, visualID 0x23
+ number of attributes: 5
+ "XV_COLORKEY" (range 0 to 16777215)
+ client settable attribute
+ client gettable attribute (current value is 2110)
+ "XV_BRIGHTNESS" (range -128 to 127)
+ client settable attribute
+ client gettable attribute (current value is 0)
+ "XV_CONTRAST" (range 0 to 255)
+ client settable attribute
+ client gettable attribute (current value is 128)
+ "XV_SATURATION" (range 0 to 255)
+ client settable attribute
+ client gettable attribute (current value is 128)
+ "XV_HUE" (range -180 to 180)
+ client settable attribute
+ client gettable attribute (current value is 0)
+ maximum XvImage size: 1024 x 1024
+ Number of image formats: 7
+ id: 0x32595559 (YUY2)
+ guid: 59555932-0000-0010-8000-00aa00389b71
+ bits per pixel: 16
+ number of planes: 1
+ type: YUV (packed)
+ id: 0x32315659 (YV12)
+ guid: 59563132-0000-0010-8000-00aa00389b71
+ bits per pixel: 12
+ number of planes: 3
+ type: YUV (planar)
+ id: 0x30323449 (I420)
+ guid: 49343230-0000-0010-8000-00aa00389b71
+ bits per pixel: 12
+ number of planes: 3
+ type: YUV (planar)
+ id: 0x36315652 (RV16)
+ guid: 52563135-0000-0000-0000-000000000000
+ bits per pixel: 16
+ number of planes: 1
+ type: RGB (packed)
+ depth: 0
+ red, green, blue masks: 0x1f, 0x3e0, 0x7c00
+ id: 0x35315652 (RV15)
+ guid: 52563136-0000-0000-0000-000000000000
+ bits per pixel: 16
+ number of planes: 1
+ type: RGB (packed)
+ depth: 0
+ red, green, blue masks: 0x1f, 0x7e0, 0xf800
+ id: 0x31313259 (Y211)
+ guid: 59323131-0000-0010-8000-00aa00389b71
+ bits per pixel: 6
+ number of planes: 3
+ type: YUV (packed)
+ id: 0x0
+ guid: 00000000-0000-0000-0000-000000000000
+ bits per pixel: 0
+ number of planes: 0
+ type: RGB (packed)
+ depth: 1
+ red, green, blue masks: 0x0, 0x0, 0x0</screen>
+
+ <para>Also note that the formats listed (YUV2, YUV12, etc) are not
+ present with every implementation of XVideo and their absence may
+ hinder some players.</para>
+
+ <para>If the result looks like:</para>
+<screen>X-Video Extension version 2.2
+screen #0
+no adaptors present</screen>
+
+ <para>Then XVideo is probably not supported for your card.</para>
+
+ <para>If XVideo is not supported for your card, this only means
+ that it will be more difficult for your display to meet the
+ computational demands of rendering video. Depending on your
+ video card and processor, though, you might still be able to
+ have a satisfying experience. You should probably read about
+ ways of improving performance in the advanced reading <xref
+ linkend="video-further-reading"/>.</para>
+
+ </sect3>
+
+ <sect3 id="video-interface-SDL">
+ <title>Simple Directmedia Layer</title>
+
+ <para>The Simple Directmedia Layer, SDL, was intended to be a
+ porting layer between &microsoft.windows;, BeOS, and &unix;,
+ allowing cross-platform applications to be developed which made
+ efficient use of sound and graphics. The SDL layer provides a
+ low-level abstraction to the hardware which can sometimes be
+ more efficient than the X11 interface.</para>
+
+ <para>The SDL can be found at <filename role="package">devel/sdl12</filename>.</para>
+
+ </sect3>
+
+ <sect3 id="video-interface-DGA">
+ <title>Direct Graphics Access</title>
+
+ <para>Direct Graphics Access is an X11 extension which allows
+ a program to bypass the X server and directly alter the
+ framebuffer. Because it relies on a low level memory mapping to
+ effect this sharing, programs using it must be run as
+ <username>root</username>.</para>
+
+ <para>The DGA extension can be tested and benchmarked by
+ &man.dga.1;. When <command>dga</command> is running, it
+ changes the colors of the display whenever a key is pressed. To
+ quit, use <keycap>q</keycap>.</para>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="video-ports">
+ <title>Ports and Packages Dealing with Video</title>
+
+ <indexterm><primary>video ports</primary></indexterm>
+ <indexterm><primary>video packages</primary></indexterm>
+
+ <para>This section discusses the software available from the
+ FreeBSD Ports Collection which can be used for video playback.
+ Video playback is a very active area of software development,
+ and the capabilities of various applications are bound to
+ diverge somewhat from the descriptions given here.</para>
+
+ <para>Firstly, it is important to know that many of the video
+ applications which run on FreeBSD were developed as Linux
+ applications. Many of these applications are still
+ beta-quality. Some of the problems that you may encounter with
+ video packages on FreeBSD include:</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>An application cannot playback a file which another
+ application produced.</para>
+ </listitem>
+
+ <listitem>
+ <para>An application cannot playback a file which the
+ application itself produced.</para>
+ </listitem>
+
+ <listitem>
+ <para>The same application on two different machines,
+ rebuilt on each machine for that machine, plays back the same
+ file differently.</para>
+ </listitem>
+
+ <listitem>
+ <para>A seemingly trivial filter like rescaling of the image
+ size results in very bad artifacts from a buggy rescaling
+ routine.</para>
+ </listitem>
+
+ <listitem>
+ <para>An application frequently dumps core.</para>
+ </listitem>
+
+ <listitem>
+ <para>Documentation is not installed with the port and can be
+ found either on the web or under the port's <filename class='directory'>work</filename>
+ directory.</para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>Many of these applications may also exhibit
+ <quote>Linux-isms</quote>. That is, there may be
+ issues resulting from the way some standard libraries are
+ implemented in the Linux distributions, or some features of the
+ Linux kernel which have been assumed by the authors of the
+ applications. These issues are not always noticed and worked around
+ by the port maintainers, which can lead to problems like
+ these:</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>The use of <filename>/proc/cpuinfo</filename> to detect
+ processor characteristics.</para>
+ </listitem>
+
+ <listitem>
+ <para>A misuse of threads which causes a program to hang upon
+ completion instead of truly terminating.</para>
+ </listitem>
+
+ <listitem>
+ <para>Software not yet in the FreeBSD Ports Collection
+ which is commonly used in conjunction with the application.</para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>So far, these application developers have been cooperative with
+ port maintainers to minimize the work-arounds needed for
+ port-ing.</para>
+
+ <sect3 id="video-mplayer">
+ <title>MPlayer</title>
+
+ <para><application>MPlayer</application> is a recently developed and rapidly developing
+ video player. The goals of the <application>MPlayer</application> team are speed and
+ flexibility on Linux and other Unices. The project was
+ started when the team founder got fed up with bad playback
+ performance on then available players. Some would say that
+ the graphical interface has been sacrificed for a streamlined
+ design. However, once
+ you get used to the command line options and the key-stroke
+ controls, it works very well.</para>
+
+ <sect4 id="video-mplayer-building">
+ <title>Building MPlayer</title>
+ <indexterm><primary>MPlayer</primary>
+ <secondary>making</secondary></indexterm>
+
+ <para><application>MPlayer</application> resides in <filename
+ role="package">multimedia/mplayer</filename>.
+ <application>MPlayer</application> performs a variety of
+ hardware checks during the build process, resulting in a
+ binary which will not be portable from one system to
+ another. Therefore, it is important to build it from
+ ports and not to use a binary package. Additionally, a
+ number of options can be specified in the <command>make</command>
+ command line, as described in the <filename>Makefile</filename> and at the start of the build:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/multimedia/mplayer</userinput>
+&prompt.root; <userinput>make</userinput>
+N - O - T - E
+
+Take a careful look into the Makefile in order
+to learn how to tune mplayer towards you personal preferences!
+For example,
+make WITH_GTK1
+builds MPlayer with GTK1-GUI support.
+If you want to use the GUI, you can either install
+/usr/ports/multimedia/mplayer-skins
+or download official skin collections from
+http://www.mplayerhq.hu/homepage/dload.html
+</screen>
+
+ <para>The default port options should be sufficient for most
+ users. However, if you need the XviD codec, you have to
+ specify the <makevar>WITH_XVID</makevar> option in the
+ command line. The default DVD device can also be defined
+ with the <makevar>WITH_DVD_DEVICE</makevar> option, by
+ default <filename>/dev/acd0</filename> will be used.</para>
+
+ <para>As of this writing, the <application>MPlayer</application> port will build its HTML
+ documentation and two executables,
+ <command>mplayer</command>, and
+ <command>mencoder</command>, which is a tool for
+ re-encoding video.</para>
+
+ <para>The HTML documentation for <application>MPlayer</application> is very informative.
+ If the reader finds the information on video hardware and
+ interfaces in this chapter lacking, the <application>MPlayer</application> documentation
+ is a very thorough supplement. You should definitely take
+ the time to read the <application>MPlayer</application>
+ documentation if you are looking for information about video
+ support in &unix;.</para>
+
+ </sect4>
+
+ <sect4 id="video-mplayer-using">
+ <title>Using MPlayer</title>
+ <indexterm><primary>MPlayer</primary>
+ <secondary>use</secondary></indexterm>
+
+ <para>Any user of <application>MPlayer</application> must set up a
+ <filename>.mplayer</filename> subdirectory of her
+ home directory. To create this necessary subdirectory,
+ you can type the following:</para>
+
+<screen>&prompt.user; <userinput>cd /usr/ports/multimedia/mplayer</userinput>
+&prompt.user; <userinput>make install-user</userinput></screen>
+
+ <para>The command options for <command>mplayer</command> are
+ listed in the manual page. For even more detail there is HTML
+ documentation. In this section, we will describe only a few
+ common uses.</para>
+
+ <para>To play a file, such as
+ <filename><replaceable>testfile.avi</replaceable></filename>,
+ through one of the various video interfaces set the
+ <option>-vo</option> option:</para>
+
+ <screen>&prompt.user; <userinput>mplayer -vo xv <replaceable>testfile.avi</replaceable></userinput></screen>
+ <screen>&prompt.user; <userinput>mplayer -vo sdl <replaceable>testfile.avi</replaceable></userinput></screen>
+ <screen>&prompt.user; <userinput>mplayer -vo x11 <replaceable>testfile.avi</replaceable></userinput></screen>
+ <screen>&prompt.root; <userinput>mplayer -vo dga <replaceable>testfile.avi</replaceable></userinput></screen>
+ <screen>&prompt.root; <userinput>mplayer -vo 'sdl:dga' <replaceable>testfile.avi</replaceable></userinput></screen>
+
+ <para>It is worth trying all of these options, as their relative
+ performance depends on many factors and will vary significantly
+ with hardware.</para>
+
+ <para>To play from a DVD, replace the
+ <filename><replaceable>testfile.avi</replaceable></filename> with <option>dvd://<replaceable>N</replaceable> -dvd-device
+ <replaceable>DEVICE</replaceable></option> where <replaceable>N</replaceable> is
+ the title number to play and
+ <filename><replaceable>DEVICE</replaceable></filename> is the
+ device node for the DVD-ROM. For example, to play title 3
+ from <filename>/dev/dvd</filename>:</para>
+
+ <screen>&prompt.root; <userinput>mplayer -vo xv dvd://3 -dvd-device /dev/dvd</userinput></screen>
+
+ <note>
+ <para>The default DVD device can be defined during the build
+ of the <application>MPlayer</application> port via the
+ <makevar>WITH_DVD_DEVICE</makevar> option. By default,
+ this device is <filename>/dev/acd0</filename>. More
+ details can be found in the port
+ <filename>Makefile</filename>.</para>
+ </note>
+
+ <para>To stop, pause, advance and so on, consult the
+ keybindings, which are output by running <command>mplayer
+ -h</command> or read the manual page.</para>
+
+ <para>Additional important options for playback are:
+ <option>-fs -zoom</option> which engages the fullscreen mode
+ and <option>-framedrop</option> which helps performance.</para>
+
+ <para>In order for the mplayer command line to not become too
+ large, the user can create a file
+ <filename>.mplayer/config</filename> and set default options
+ there:</para>
+<programlisting>vo=xv
+fs=yes
+zoom=yes</programlisting>
+
+ <para>Finally, <command>mplayer</command> can be used to rip a
+ DVD title into a <filename>.vob</filename> file. To dump
+ out the second title from a DVD, type this:</para>
+
+ <screen>&prompt.root; <userinput>mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd</userinput></screen>
+
+ <para>The output file, <filename>out.vob</filename>, will be
+ MPEG and can be manipulated by the other packages described
+ in this section.</para>
+
+ </sect4>
+ <sect4 id="video-mencoder">
+ <title>mencoder</title>
+ <indexterm>
+ <primary>mencoder</primary>
+ </indexterm>
+
+ <para>Before using
+ <command>mencoder</command> it is a good idea to
+ familiarize yourself with the options from the HTML
+ documentation. There is a manual page, but it is not very
+ useful without the HTML documentation. There are innumerable ways to
+ improve quality, lower bitrate, and change formats, and some
+ of these tricks may make the difference between good
+ or bad performance. Here are a couple of examples to get
+ you going. First a simple copy:</para>
+
+ <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac copy -ovc copy -o <replaceable>output.avi</replaceable></userinput></screen>
+
+ <para>Improper combinations of command line options can yield
+ output files that are
+ unplayable even by <command>mplayer</command>. Thus, if you
+ just want to rip to a file, stick to the <option>-dumpfile</option>
+ in <command>mplayer</command>.</para>
+
+ <para>To convert <filename><replaceable>input.avi</replaceable></filename> to the MPEG4
+ codec with MPEG3 audio encoding (<filename role="package">audio/lame</filename> is required):</para>
+
+ <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac mp3lame -lameopts br=192 \
+ -ovc lavc -lavcopts vcodec=mpeg4:vhq -o <replaceable>output.avi</replaceable></userinput></screen>
+
+ <para>This has produced output playable by <command>mplayer</command>
+ and <command>xine</command>.</para>
+
+ <para><filename><replaceable>input.avi</replaceable></filename> can be replaced with
+ <option>dvd://1 -dvd-device /dev/dvd</option> and run as
+ <username>root</username> to re-encode a DVD title
+ directly. Since you are likely to be dissatisfied with
+ your results the first time around, it is recommended you
+ dump the title to a file and work on the file.</para>
+ </sect4>
+
+ </sect3>
+
+ <sect3 id="video-xine">
+ <title>The xine Video Player</title>
+
+ <para>The <application>xine</application> video player is a project of wide scope aiming not only at being an
+ all in one video solution, but also in producing a reusable base
+ library and a modular executable which can be extended with
+ plugins. It comes both as a package and as a port, <filename
+ role="package">multimedia/xine</filename>.</para>
+
+ <para>The <application>xine</application> player
+ is still very rough around the edges, but it is clearly off to a
+ good start. In practice, <application>xine</application> requires either a fast CPU with a
+ fast video card, or support for the XVideo extension. The GUI is
+ usable, but a bit clumsy.</para>
+
+ <para>As of this writing, there is no input module shipped with
+ <application>xine</application> which will play CSS encoded DVDs. There are third party
+ builds which do have modules for this built in them, but none
+ of these are in the FreeBSD Ports Collection.</para>
+
+ <para>Compared to <application>MPlayer</application>, <application>xine</application> does more for the user, but at the
+ same time, takes some of the more fine-grained control away from
+ the user. The <application>xine</application> video player
+ performs best on XVideo interfaces.</para>
+
+ <para>By default, <application>xine</application> player will
+ start up in a graphical user interface. The menus can then be
+ used to open a specific file:</para>
+
+ <screen>&prompt.user; <userinput>xine</userinput></screen>
+
+ <para>Alternatively, it may be invoked to play a file immediately
+ without the GUI with the command:</para>
+
+ <screen>&prompt.user; <userinput>xine -g -p <replaceable>mymovie.avi</replaceable></userinput></screen>
+
+ </sect3>
+
+ <sect3 id="video-ports-transcode">
+ <title>The transcode Utilities</title>
+
+ <para>The software <application>transcode</application> is not a player, but a suite of tools for
+ re-encoding video and audio files. With <application>transcode</application>, one has the
+ ability to merge video files, repair broken files, using command
+ line tools with <filename>stdin/stdout</filename> stream
+ interfaces.</para>
+
+ <para>A great number of options can be specified during
+ the build from the <filename
+ role="package">multimedia/transcode</filename> port, we recommend the
+ following command line to build
+ <application>transcode</application>:</para>
+
+ <screen>&prompt.root; <userinput>make WITH_OPTIMIZED_CFLAGS=yes WITH_LIBA52=yes WITH_LAME=yes WITH_OGG=yes \
+WITH_MJPEG=yes -DWITH_XVID=yes</userinput></screen>
+
+ <para>The proposed settings should be sufficient for most users.</para>
+
+ <para>To illustrate <command>transcode</command> capacities, one
+ example to show how to convert a DivX file into a PAL MPEG-1
+ file (PAL VCD):</para>
+
+ <screen>&prompt.user; <userinput>transcode -i <replaceable>input.avi</replaceable> -V --export_prof vcd-pal -o output_vcd</userinput>
+&prompt.user; <userinput>mplex -f 1 -o <replaceable>output_vcd.mpg output_vcd.m1v output_vcd.mpa</replaceable></userinput></screen>
+
+ <para>The resulting MPEG file,
+ <filename><replaceable>output_vcd.mpg</replaceable></filename>, is ready to be played with
+ <application>MPlayer</application>. You could even burn the
+ file on a CD-R media to create a Video CD, in this case you will
+ need to install and use both <filename
+ role="package">multimedia/vcdimager</filename> and <filename
+ role="package">sysutils/cdrdao</filename> programs.</para>
+
+ <para>There is a manual page for <command>transcode</command>, but
+ you should also consult the <ulink
+ url="http://www.transcoding.org/cgi-bin/transcode">transcode
+ wiki</ulink> for further information and examples.</para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="video-further-reading">
+ <title>Further Reading</title>
+
+ <para>The various video software packages for FreeBSD are
+ developing rapidly. It is quite possible that in the near
+ future many of the problems discussed here will have been
+ resolved. In the mean time, those who
+ want to get the very most out of FreeBSD's A/V capabilities will
+ have to cobble together knowledge from several FAQs and tutorials
+ and use a few different applications. This section exists to
+ give the reader pointers to such additional information.</para>
+
+ <para>The
+ <ulink url="http://www.mplayerhq.hu/DOCS/">MPlayer documentation</ulink>
+ is very technically informative.
+ These documents should probably be consulted by anyone wishing
+ to obtain a high level of expertise with &unix; video. The
+ <application>MPlayer</application> mailing list is hostile to anyone who has not bothered
+ to read the documentation, so if you plan on making bug reports
+ to them, RTFM.</para>
+
+ <para>The
+ <ulink url="http://dvd.sourceforge.net/xine-howto/en_GB/html/howto.html"> xine HOWTO</ulink>
+ contains a chapter on performance improvement
+ which is general to all players.</para>
+
+ <para>Finally, there are some other promising applications which
+ the reader may try:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para><ulink
+ url="http://avifile.sourceforge.net/">Avifile</ulink> which
+ is also a port <filename
+ role='package'>multimedia/avifile</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://www.dtek.chalmers.se/groups/dvd/">Ogle</ulink>
+ which is also a port <filename
+ role='package'>multimedia/ogle</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://xtheater.sourceforge.net/">Xtheater</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><filename
+ role="package">multimedia/dvdauthor</filename>, an open
+ source package for authoring DVD content.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="tvcard">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Josef</firstname>
+ <surname>El-Rayes</surname>
+ <contrib>Original contribution by </contrib>
+ </author>
+ </authorgroup>
+ <authorgroup>
+ <author>
+ <firstname>Marc</firstname>
+ <surname>Fonvieille</surname>
+ <contrib>Enhanced and adapted by </contrib>
+ <!-- 02 January 2004 -->
+ </author>
+ </authorgroup>
+ </sect1info>
+
+ <title>Setting Up TV Cards</title>
+ <indexterm>
+ <primary>TV cards</primary>
+ </indexterm>
+
+ <sect2>
+ <title>Introduction</title>
+
+ <para>TV cards allow you to watch broadcast or cable TV on your
+ computer. Most of them accept composite video via an RCA or
+ S-video input and some of these cards come with a FM
+ radio tuner.</para>
+
+ <para>&os; provides support for PCI-based TV cards using a
+ Brooktree Bt848/849/878/879 or a Conexant CN-878/Fusion 878a
+ Video Capture Chip with the &man.bktr.4; driver. You must
+ also ensure the board comes with a supported tuner, consult
+ the &man.bktr.4; manual page for a list of supported
+ tuners.</para>
+ </sect2>
+
+ <sect2>
+ <title>Adding the Driver</title>
+
+ <para>To use your card, you will need to load the &man.bktr.4;
+ driver, this can be done by adding the following line to the
+ <filename>/boot/loader.conf</filename> file like this:</para>
+
+ <programlisting>bktr_load="YES"</programlisting>
+
+ <para>Alternatively, you may statically compile the support for
+ the TV card in your kernel, in that case add the following
+ lines to your kernel configuration:</para>
+
+ <programlisting>device bktr
+device iicbus
+device iicbb
+device smbus</programlisting>
+
+ <para>These additional device drivers are necessary because of the
+ card components being interconnected via an I2C bus. Then build
+ and install a new kernel.</para>
+
+ <para>Once the support was added to your system, you have to
+ reboot your machine. During the boot process, your TV card
+ should show up, like this:</para>
+
+ <programlisting>bktr0: &lt;BrookTree 848A&gt; mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0
+iicbb0: &lt;I2C bit-banging driver&gt; on bti2c0
+iicbus0: &lt;Philips I2C bus&gt; on iicbb0 master-only
+iicbus1: &lt;Philips I2C bus&gt; on iicbb0 master-only
+smbus0: &lt;System Management Bus&gt; on bti2c0
+bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting>
+
+ <para>Of course these messages can differ according to your
+ hardware. However you should check if the tuner is correctly
+ detected; it is still possible to override some of the
+ detected parameters with &man.sysctl.8; MIBs and kernel
+ configuration file options. For example, if you want to force
+ the tuner to a Philips SECAM tuner, you should add the
+ following line to your kernel configuration file:</para>
+
+ <programlisting>options OVERRIDE_TUNER=6</programlisting>
+
+ <para>or you can directly use &man.sysctl.8;:</para>
+
+ <screen>&prompt.root; <userinput>sysctl hw.bt848.tuner=6</userinput></screen>
+
+ <para>See the &man.bktr.4; manual page and the
+ <filename>/usr/src/sys/conf/NOTES</filename> file for more
+ details on the available options.</para>
+ </sect2>
+
+ <sect2>
+ <title>Useful Applications</title>
+
+ <para>To use your TV card you need to install one of the
+ following applications:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename role="package">multimedia/fxtv</filename>
+ provides TV-in-a-window and image/audio/video capture
+ capabilities.</para>
+ </listitem>
+ <listitem>
+ <para><filename role="package">multimedia/xawtv</filename>
+ is also a TV application, with the same features as
+ <application>fxtv</application>.</para>
+ </listitem>
+ <listitem>
+ <para><filename role="package">misc/alevt</filename> decodes
+ and displays Videotext/Teletext.</para>
+ </listitem>
+ <listitem>
+ <para><filename role="package">audio/xmradio</filename>, an
+ application to use the FM radio tuner coming with some
+ TV cards.</para>
+ </listitem>
+ <listitem>
+ <para><filename role="package">audio/wmtune</filename>, a handy
+ desktop application for radio tuners.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>More applications are available in the &os; Ports
+ Collection.</para>
+ </sect2>
+
+ <sect2>
+ <title>Troubleshooting</title>
+
+ <para>If you encounter any problem with your TV card, you should
+ check at first if the video capture chip and the tuner are
+ really supported by the &man.bktr.4; driver and if you used the right
+ configuration options. For more support and various questions
+ about your TV card you may want to contact and use the
+ archives of the &a.multimedia.name; mailing list.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="mythtv">
+ <title>MythTV</title>
+
+ <para>MythTV is an open source <acronym
+ role="Personal Video Recorder">PVR</acronym> software
+ project.</para>
+
+ <para>It is well-known in the &linux; world as a complex
+ application with many dependencies, and therefore difficult to
+ install. The &os; ports system simplifies much of the process, but
+ some components must be set up manually. This section is intended
+ to help and guide in setting up MythTV.</para>
+
+ <sect2>
+ <title>Hardware</title>
+
+ <para>MythTV is designed to utilise <acronym
+ role="Video for Linux">V4L</acronym> to access video input devices
+ such as encoders and tuners. At this time, MythTV works best with
+ <acronym role="Universal Serial Bus">USB</acronym> DVB-S/C/T cards
+ supported by <filename
+ role="package">multimedia/webcamd</filename> because
+ <application>webcamd</application> provides a <acronym
+ role="Video for Linux">V4L</acronym> userland application. Any
+ <acronym role="Digital Video Broadcasting">DVB</acronym> card
+ supported by <application>webcamd</application> should work with
+ MythTV, but a list of known working cards can be found <ulink
+ url="http://wiki.freebsd.org/WebcamCompat">here</ulink>. There
+ are also drivers available for Hauppauge cards in the following
+ packages: <filename role="package">multimedia/pvr250</filename>
+ and <filename role="package">multimedia/pvrxxx</filename>, but
+ they provide a non-standard driver interface that does not work
+ with versions of MythTV greater than 0.23.</para>
+
+ <para><ulink url="http://wiki.freebsd.org/HTPC">HTPC</ulink>
+ contains a list of all available <acronym
+ role="Digital Video Broadcasting">DVB</acronym> drivers.</para>
+ </sect2>
+
+ <sect2>
+ <title>Dependencies</title>
+
+ <para>Being flexible and modular, MythTV allows the user to have the
+ frontend and backend on different machines.</para>
+
+ <para>For the frontend, <filename
+ role="package">multimedia/mythtv-frontend</filename> is required,
+ as well as an X server, which can be found in <filename
+ role="package">x11/xorg</filename>. Ideally, the frontend
+ computer also has a video card that supports <acronym
+ role="X-Video Motion Compensation">XvMC</acronym> and,
+ optionally, a <acronym
+ role="Linux Infrared Remote Control">LIRC</acronym>-compatible
+ remote.</para>
+
+ <para>For the backend, <filename
+ role="package">multimedia/mythtv</filename> is required, as well
+ as a &mysql; database, and optionally a tuner and storage for
+ recordings. The &mysql; package should be automatically installed
+ as a dependency when installing <filename
+ role="package">multimedia/mythtv</filename>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Setting up MythTV</title>
+
+ <para>To install MythTV, use the following steps. First, install
+ MythTV from the &os; Ports collection:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/multimedia/mythtv</userinput>
+&prompt.root; <userinput>make install</userinput></screen>
+
+ <para>Set up the MythTV database:</para>
+
+ <screen>&prompt.root; <userinput>mysql -uroot -p < /usr/local/share/mythtv/database/mc.sql</userinput></screen>
+
+ <para>Configure the backend:</para>
+
+ <screen>&prompt.root; <userinput>mythtv-setup</userinput></screen>
+
+ <para>Start the backend:</para>
+
+ <screen>&prompt.root; <userinput>echo 'mythbackend_enable="YES"' >> /etc/rc.conf</userinput>
+&prompt.root; <userinput>/usr/local/etc/rc.d/mythbackend start</userinput></screen>
+ </sect2>
+ </sect1>
+
+ <sect1 id="scanners">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Marc</firstname>
+ <surname>Fonvieille</surname>
+ <contrib>Written by </contrib>
+ <!-- 04 August 2004 -->
+ </author>
+ </authorgroup>
+ </sect1info>
+
+ <title>Image Scanners</title>
+ <indexterm>
+ <primary>image scanners</primary>
+ </indexterm>
+
+ <sect2>
+ <title>Introduction</title>
+
+ <para>In &os;, access to image scanners is provided
+ by the <application>SANE</application> (Scanner Access Now
+ Easy) <acronym role="Application Programming
+ Interface">API</acronym> available through the &os; Ports
+ Collection. <application>SANE</application> will also use
+ some &os; device drivers to access to the scanner
+ hardware.</para>
+
+ <para>&os; supports both SCSI and USB scanners. Be sure your
+ scanner is supported by <application>SANE</application> prior
+ to performing any configuration.
+ <application>SANE</application> has a <ulink
+ url="http://www.sane-project.org/sane-supported-devices.html">supported
+ devices</ulink> list that can provide you with information
+ about the support for a scanner and its status. On systems
+ prior to &os;&nbsp;8.X the
+ &man.uscanner.4; manual page also provides a list of supported
+ USB scanners.</para>
+ </sect2>
+
+ <sect2>
+ <title>Kernel Configuration</title>
+
+ <para>As mentioned above both SCSI and USB interfaces are
+ supported. According to your scanner interface, different
+ device drivers are required.</para>
+
+ <sect3 id="scanners-kernel-usb">
+ <title>USB Interface</title>
+
+ <para>The <filename>GENERIC</filename> kernel by default
+ includes the device drivers needed to support USB scanners.
+ Should you decide to use a custom kernel, be sure that the
+ following lines are present in your kernel configuration
+ file:</para>
+
+ <programlisting>device usb
+device uhci
+device ohci
+device ehci</programlisting>
+
+ <para>On systems prior to &os;&nbsp;8.X, the following line is
+ also needed:</para>
+
+ <programlisting>device uscanner</programlisting>
+
+ <para>On these versions of &os;, the &man.uscanner.4; device
+ driver provides support for the USB scanners. Since
+ &os;&nbsp;8.0, this support is directly provided by
+ the &man.libusb.3; library.</para>
+
+ <para>After rebooting with the correct kernel,
+ plug in your USB scanner. A
+ line showing the detection of your
+ scanner should appear in the system message buffer
+ (&man.dmesg.8;):</para>
+
+ <screen>ugen0.2: &lt;EPSON&gt; at usbus0</screen>
+
+ <para>or on a &os;&nbsp;7.X system:</para>
+
+ <screen>uscanner0: EPSON EPSON Scanner, rev 1.10/3.02, addr 2</screen>
+
+ <para>These messages show that our scanner is using
+ either <filename>/dev/ugen0.2</filename> or
+ <filename>/dev/uscanner0</filename> as device node according
+ to the &os; version we run. For this example, a
+ &epson.perfection;&nbsp;1650 USB scanner was used.</para>
+ </sect3>
+
+ <sect3>
+ <title>SCSI Interface</title>
+
+ <para>If your scanner comes with a SCSI interface, it is
+ important to know which SCSI controller board you will use.
+ According to the SCSI chipset used, you will have to tune
+ your kernel configuration file. The
+ <filename>GENERIC</filename> kernel supports the most common
+ SCSI controllers. Be sure to read the
+ <filename>NOTES</filename> file
+ and add the correct line to your kernel
+ configuration file. In addition to the SCSI adapter driver,
+ you need to have the following lines in your kernel
+ configuration file:</para>
+
+ <programlisting>device scbus
+device pass</programlisting>
+
+ <para>Once your kernel has been properly compiled and installed, you should
+ be able to see the devices in the system message buffer,
+ when booting:</para>
+
+ <screen>pass2 at aic0 bus 0 target 2 lun 0
+pass2: &lt;AGFA SNAPSCAN 600 1.10&gt; Fixed Scanner SCSI-2 device
+pass2: 3.300MB/s transfers</screen>
+
+ <para>If your scanner was not powered-on at system boot, it is
+ still possible to manually force the detection by performing
+ a SCSI bus scan with the &man.camcontrol.8; command:</para>
+
+ <screen>&prompt.root; <userinput>camcontrol rescan all</userinput>
+Re-scan of bus 0 was successful
+Re-scan of bus 1 was successful
+Re-scan of bus 2 was successful
+Re-scan of bus 3 was successful</screen>
+
+ <para>Then the scanner will appear in the SCSI devices
+ list:</para>
+
+ <screen>&prompt.root; <userinput>camcontrol devlist</userinput>
+&lt;IBM DDRS-34560 S97B&gt; at scbus0 target 5 lun 0 (pass0,da0)
+&lt;IBM DDRS-34560 S97B&gt; at scbus0 target 6 lun 0 (pass1,da1)
+&lt;AGFA SNAPSCAN 600 1.10&gt; at scbus1 target 2 lun 0 (pass3)
+&lt;PHILIPS CDD3610 CD-R/RW 1.00&gt; at scbus2 target 0 lun 0 (pass2,cd0)</screen>
+
+ <para>More details about SCSI devices are available in the
+ &man.scsi.4; and &man.camcontrol.8; manual pages.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>SANE Configuration</title>
+
+ <para>The <application>SANE</application> system is
+ split in two parts: the backends (<filename
+ role="package">graphics/sane-backends</filename>) and the
+ frontends (<filename
+ role="package">graphics/sane-frontends</filename>). The
+ backends part provides access to the scanner itself. The
+ <application>SANE</application>'s <ulink
+ url="http://www.sane-project.org/sane-supported-devices.html">supported
+ devices</ulink> list specifies which backend will support your
+ image scanner. It is mandatory to determine the correct
+ backend for your scanner if you want to be able to use your
+ device. The frontends part provides the graphical scanning
+ interface (<application>xscanimage</application>).</para>
+
+ <para>The first step is to install the <filename
+ role="package">graphics/sane-backends</filename> port or
+ package. Then, use the <command>sane-find-scanner</command>
+ command to check the scanner detection by the
+ <application>SANE</application> system:</para>
+
+ <screen>&prompt.root; <userinput>sane-find-scanner -q</userinput>
+found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3</screen>
+
+ <para>The output will show the interface type of the scanner and
+ the device node used to attach the scanner to the system. The
+ vendor and the product model may not appear, it is not
+ important.</para>
+
+ <note>
+ <para>Some USB scanners require you to load a firmware, this
+ is explained in the backend manual page. You should also read
+ &man.sane-find-scanner.1; and &man.sane.7; manual
+ pages.</para>
+ </note>
+
+ <para>Now we have to check if the scanner will be identified by
+ a scanning frontend. By default, the
+ <application>SANE</application> backends comes with a command
+ line tool called &man.scanimage.1;. This command allows you
+ to list the devices and to perform an image acquisition from
+ the command line. The <option>-L</option> option is used to
+ list the scanner devices:</para>
+
+ <screen>&prompt.root; <userinput>scanimage -L</userinput>
+device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner</screen>
+
+ <para>Or, for example with the USB scanner used in the <xref
+ linkend="scanners-kernel-usb"/>:</para>
+
+ <screen>&prompt.root; <userinput>scanimage -L</userinput>
+device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner</screen>
+
+ <para>This output comes from a &os;&nbsp;8.X system, the
+ <literal>'epson2:libusb:/dev/usb:/dev/ugen0.2'</literal> item
+ gives us the backend name (<literal>epson2</literal>) and the
+ device node (<literal>/dev/ugen0.2</literal>) used by our
+ scanner.</para>
+
+ <note>
+ <para>No output or a message saying that no scanners were
+ identified indicates that &man.scanimage.1; is unable to
+ identify the scanner. If this happens, you will need to edit
+ the backend configuration file and define the scanner device
+ used. The <filename
+ class="directory">/usr/local/etc/sane.d/</filename> directory
+ contains all backend configuration files. This
+ identification problem does appear with certain USB
+ scanners.</para>
+
+ <para>For example, with the USB scanner used in the <xref
+ linkend="scanners-kernel-usb"/>, under &os;&nbsp;8.X the
+ scanner is perfectly detected and working but under prior
+ versions of &os; (where &man.uscanner.4; driver is used)
+ <command>sane-find-scanner</command> gives us the following
+ information:</para>
+
+ <screen>&prompt.root; <userinput>sane-find-scanner -q</userinput>
+found USB scanner (UNKNOWN vendor and product) at device /dev/uscanner0</screen>
+ <para>The scanner is correctly detected, it uses the USB
+ interface and is attached to the
+ <filename>/dev/uscanner0</filename> device node. We can now
+ check if the scanner is correctly identified:</para>
+
+ <screen>&prompt.root; <userinput>scanimage -L</userinput>
+
+No scanners were identified. If you were expecting something different,
+check that the scanner is plugged in, turned on and detected by the
+sane-find-scanner tool (if appropriate). Please read the documentation
+which came with this software (README, FAQ, manpages).</screen>
+
+ <para>Since the scanner is not identified, we will need to edit
+ the <filename>/usr/local/etc/sane.d/epson2.conf</filename>
+ file. The scanner model used was the &epson.perfection;&nbsp;1650,
+ so we know the scanner will use the <literal>epson2</literal>
+ backend. Be sure to read the help comments in the backends
+ configuration files. Line changes are quite simple: comment
+ out all lines that have the wrong interface for your scanner
+ (in our case, we will comment out all lines starting with the
+ word <literal>scsi</literal> as our scanner uses the USB
+ interface), then add at the end of the file a line specifying
+ the interface and the device node used. In this case, we add
+ the following line:</para>
+
+ <programlisting>usb /dev/uscanner0</programlisting>
+
+ <para>Please be sure to read the comments provided in the
+ backend configuration file as well as the backend manual page
+ for more details and correct syntax to use. We can now verify
+ if the scanner is identified:</para>
+
+ <screen>&prompt.root; <userinput>scanimage -L</userinput>
+device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner</screen>
+
+ <para>Our USB scanner has been identified. It is not important
+ if the brand and the model do not match the scanner. The key item to be
+ concerned with is the
+ <literal>`epson:/dev/uscanner0'</literal> field, which give us
+ the right backend name and the right device node.</para>
+ </note>
+
+ <para>Once the <command>scanimage -L</command> command is able
+ to see the scanner, the configuration is complete. The device
+ is now ready to scan.</para>
+
+ <para>While &man.scanimage.1; does allow us to perform an
+ image acquisition from the command line, it is preferable to
+ use a graphical user interface to perform image scanning.
+ <application>SANE</application> offers a simple but efficient
+ graphical interface: <application>xscanimage</application>
+ (<filename
+ role="package">graphics/sane-frontends</filename>).</para>
+
+ <para><application>Xsane</application> (<filename
+ role="package">graphics/xsane</filename>) is another popular
+ graphical scanning frontend. This frontend offers advanced
+ features such as various scanning mode (photocopy, fax, etc.),
+ color correction, batch scans, etc. Both of these applications
+ are usable as a <application>GIMP</application>
+ plugin.</para>
+ </sect2>
+
+ <sect2>
+ <title>Giving Other Users Access to the Scanner</title>
+
+ <para>All previous operations have been done with
+ <username>root</username> privileges. You may however, need
+ other users to have access
+ to the scanner. The user will need read and write
+ permissions to the device node used by the scanner. As an
+ example, our USB scanner uses the device node
+ <filename>/dev/ugen0.2</filename> which is in fact just a
+ symlink to the real device node called
+ <filename>/dev/usb/0.2.0</filename> (a quick look at the
+ contents of the <filename class="directory">/dev</filename>
+ directory will confirm it). Both, the symlink and the
+ device node, are owned respectively by the
+ <groupname>wheel</groupname> and the
+ <groupname>operator</groupname> groups. Adding the user
+ <username><replaceable>joe</replaceable></username> to these
+ groups will allow him to use
+ the scanner but, for obvious security reasons, you should
+ think twice before adding a user to any group, especially the
+ <groupname>wheel</groupname> group. A better solution would
+ be creating a specific group for using the USB devices
+ and make the scanner device accessible to members of this
+ group.</para>
+
+ <para>So we will use, for example, a group called
+ <groupname><replaceable>usb</replaceable></groupname>. The
+ first step is the creation of this group with the help of the
+ &man.pw.8; command:</para>
+
+ <screen>&prompt.root; <userinput>pw groupadd usb</userinput></screen>
+
+ <para>Then we have to make the <filename>/dev/ugen0.2</filename>
+ symlink and the <filename>/dev/usb/0.2.0</filename> device node accessible to the <groupname>usb</groupname> group
+ with the correct write permissions (<literal>0660</literal> or
+ <literal>0664</literal>), because by default only the owner of
+ these files (<username>root</username>) can write to them.
+ All of this is done by adding the following
+ lines to the <filename>/etc/devfs.rules</filename> file:</para>
+
+ <programlisting>[system=5]
+add path ugen0.2 mode 0660 group usb
+add path usb/0.2.0 mode 0666 group usb</programlisting>
+
+ <para>&os;&nbsp;7.X users will probably need the following lines with the
+ correct device node <filename>/dev/uscanner0</filename>:</para>
+
+ <programlisting>[system=5]
+add path uscanner0 mode 660 group usb</programlisting>
+
+ <para>Then add the following to
+ <filename>/etc/rc.conf</filename> and reboot the
+ machine:</para>
+
+ <programlisting>devfs_system_ruleset="system"</programlisting>
+
+ <para>More information regarding these lines can be found in the
+ &man.devfs.8; manual page.</para>
+
+ <para>Now, one will just have to add users to the
+ <groupname><replaceable>usb</replaceable></groupname> group to
+ allow the access to the scanner:</para>
+
+ <screen>&prompt.root; <userinput>pw groupmod usb -m <replaceable>joe</replaceable></userinput></screen>
+
+ <para>For more details read the &man.pw.8; manual page.</para>
+ </sect2>
+ </sect1>
+</chapter>