aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/handbook/multimedia/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/handbook/multimedia/chapter.xml1514
1 files changed, 672 insertions, 842 deletions
diff --git a/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
index f14f0ea81c..529bd216e4 100644
--- a/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
@@ -21,70 +21,62 @@
<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
+ <para>&os; supports a wide variety of sound cards, allowing users
+ to enjoy high fidelity output from a &os; system. 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>
+ 3 (<acronym>MP3</acronym>), Waveform Audio File
+ (<acronym>WAV</acronym>), Ogg Vorbis, and other formats. The
+ &os; Ports Collection contains many applications for editing
+ recorded audio, adding sound effects, and controlling attached
+ MIDI devices.</para>
+
+ <para>&os; also supports the playback of video files and DVDs.
+ The &os; Ports Collection contains applications to encode,
+ convert, and playback various video media.</para>
+
+ <para>This chapter describes how to configure sound cards, video
+ playback, TV tuner cards, and scanners on &os;. It also
+ describes some of the applications which are available for
+ using these devices.</para>
+
+ <para>After reading this chapter, you will know how to:</para>
<itemizedlist>
<listitem>
- <para>How to configure your system so that your sound card
- is recognized.</para>
+ <para>Configure a sound card on os;.</para>
</listitem>
<listitem>
- <para>Methods to test whether your card is working.</para>
+ <para>Troubleshoot the sound setup.</para>
</listitem>
<listitem>
- <para>How to troubleshoot your sound setup.</para>
+ <para>Playback and encode MP3s and other audio.</para>
</listitem>
<listitem>
- <para>How to playback and encode MP3s and other audio.</para>
+ <para>Prepare a &os; system for video playback.</para>
</listitem>
<listitem>
- <para>How video is supported by the X server.</para>
+ <para>Playback DVDs, <filename>.mpg</filename>, and
+ <filename>.avi</filename> files.</para>
</listitem>
<listitem>
- <para>Some video player/encoder ports which give good
- results.</para>
+ <para>Rip CD and DVD content into files.</para>
</listitem>
<listitem>
- <para>How to playback DVDs, <filename>.mpg</filename> and
- <filename>.avi</filename> files.</para>
+ <para>Configure a TV card.</para>
</listitem>
<listitem>
- <para>How to rip CD and DVD content into files.</para>
+ <para>Install and setup MythTV on &os;</para>
</listitem>
<listitem>
- <para>How to configure a TV card.</para>
+ <para>Configure an image scanner.</para>
</listitem>
<listitem>
@@ -100,10 +92,9 @@
</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>
+ <para>Audio CDs have specialized encodings which differ from the
+ usual ISO-filesystem. This means that they should not be
+ mounted using &man.mount.8;.</para>
</warning>
</sect1>
@@ -134,101 +125,92 @@
<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>
+ <para>Before beginning the configuration, determine the model of
+ the sound card and the chip it uses. &os; supports a wide
+ variety of sound cards. Check the supported audio devices
+ list of the <ulink url="&rel.current.hardware;">Hardware
+ Notes</ulink> to see if the card is supported and which &os;
+ driver it uses.</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>
+ <para>In order to use the sound device, the proper device driver
+ must be loaded. This may be accomplished in one of two ways.
+ The easiest way is to load a kernel module for the sound card
+ with &man.kldload.8;. This example loads the driver for a
+ Creative &soundblaster; Live! sound card:</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>
+ <para>To automate the loading of this driver at boot time, add the
+ driver to <filename>/boot/loader.conf</filename>. The line for
+ this driver is:</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>
+ <para>Other available sound modules are listed in
+ <filename>/boot/defaults/loader.conf</filename>. When unsure
+ which driver to use, 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>This is a metadriver which loads all of the most common
+ sound drivers and can be used to speed up the search for the
+ correct driver. It is also possible to load all sound drivers
+ by adding the metadriver to
+ <filename>/boot/loader.conf</filename>.</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>To determine which driver was selected for the sound card
+ after loading the <filename>snd_driver</filename> metadriver,
+ type <command>cat /dev/sndstat</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>
+ <para>Users who prefer to statically compile in support for the
+ sound card in a custom kernel should refer to the instructions
+ in the next section. For more information about recompiling a
+ kernel, refer to <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>
+ <para>When using a custom kernel to provide sound support, make
+ sure that the audio framework driver exists in the custom 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>
+ <para>Next, add support for the sound card. Therefore, you need
+ to know which driver supports the card. To continue the example
+ of the Creative &soundblaster; Live! sound card from the
+ previous section, use the following line in the custom kernel
+ configuration file:</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
+ found in <filename>/usr/src/sys/conf/NOTES</filename>.</para>
+
+ <para>Non-PnP ISA sound cards may require the IRQ and I/O port
+ settings of the card to be added to
+ <filename>/boot/device.hints</filename>. During the boot
+ process, &man.loader.8; reads this file and passes 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
+ <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
+ <para>If the card uses the <literal>0x220</literal> I/O port and
+ IRQ <literal>5</literal>, these lines must also be added to
<filename>/boot/device.hints</filename>:</para>
<programlisting>hint.sbc.0.at="isa"
@@ -240,31 +222,32 @@ 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 syntax used in
+ <filename>/boot/device.hints</filename> is described in
+ &man.sound.4; and the manual page for the driver of the sound
+ card.</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>
+ cases, the IRQ or other settings may need to be changed to
+ match the card. Refer to &man.snd.sbc.4; 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>
+ <para>After rebooting into the custom kernel, or after loading
+ the required module, the sound card should appear in the system
+ message buffer. Run &man.dmesg.8; and look for a message
+ 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>
+ <para>The status of the sound card may also be checked using this
+ command:</para>
<screen>&prompt.root; <userinput>cat /dev/sndstat</userinput>
FreeBSD Audio Driver (newpcm)
@@ -272,46 +255,43 @@ 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
+ <para>The output may vary between systems. 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
+ review the kernel configuration file 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
+ <para>If all goes well, the sound card should now work in os;. If
+ the CD-ROM or DVD-ROM drive's audio-out pins are properly
+ connected to the sound card, one can insert an audio 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>
+ role="package">audio/workman</filename> provide a friendlier
+ interface. The <filename role="package">audio/mpg123</filename>
+ port can be installed 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>
+ <para>Another quick way to test the card is to send data to
+ <filename>/dev/dsp</filename>:</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>
+ be any file. This command should produce some noise, confirming
+ that 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
+ <para>The <devicename>/dev/dsp*</devicename> device nodes will
+ be created automatically as needed. When not in use, 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>
+ <para>Sound card mixer levels can be changed using &man.mixer.8;.
+ More details can be found in &man.mixer.8;.</para>
<sect3 id="troubleshooting">
<title>Common Problems</title>
@@ -356,9 +336,8 @@ kld snd_ich (1p/2r/0v channels duplex default)</screen>
<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
+ 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>
@@ -370,9 +349,9 @@ kld snd_ich (1p/2r/0v channels duplex default)</screen>
<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
+ sometimes be enumerated before the sound card and the sound
+ card 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>
@@ -397,16 +376,16 @@ pcm7: &lt;HDA Realtek ALC889 PCM #3 Digital&gt; at cad 2 nid 1 on hdac1
<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>
+ ALC889</literal>). To use the sound card as the default
+ playback device, change <varname>hw.snd.default_unit</varname>
+ to the unit that should be used for playback:</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
+ device to use. In this example, it should be
+ <literal>4</literal>. 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>
@@ -426,20 +405,13 @@ pcm7: &lt;HDA Realtek ALC889 PCM #3 Digital&gt; at cad 2 nid 1 on hdac1
<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>
+ are able to play simultaneously. &os; uses <emphasis>Virtual
+ Sound Channels</emphasis>, which can be enabled using
+ &man.sysctl.8;. Virtual channels allow one to multiplex the
+ 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>
+ <para>To set the number of virtual channels, three
+ &man.sysctl.8; knobs are available:</para>
<screen>&prompt.root; <userinput>sysctl dev.pcm.0.play.vchans=4</userinput>
&prompt.root; <userinput>sysctl dev.pcm.0.rec.vchans=4</userinput>
@@ -450,26 +422,26 @@ pcm7: &lt;HDA Realtek ALC889 PCM #3 Digital&gt; at cad 2 nid 1 on hdac1
<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
+ and recording, and are configurable after 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>
+ indicates how many virtual channels will be given to devices
+ when they are attached. Refer to &man.pcm.4; 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
+ <para>The number of virtual channels for a device cannot be
+ changed 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>
+ automatically be allocated transparently to a program that
+ requests <filename>/dev/dsp0</filename>.</para>
</sect2>
<sect2>
@@ -486,18 +458,20 @@ pcm7: &lt;HDA Realtek ALC889 PCM #3 Digital&gt; at cad 2 nid 1 on hdac1
<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>
+ hardcoded in the source code of the &man.pcm.4; driver. There
+ are many different applications and daemons that allow values to
+ be set 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. This is accomplished by
+ defining the appropriate values in
+ <filename>/boot/device.hints</filename>, as seen in this
+ example:</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>
+ <literal>50</literal> when the &man.pcm.4; module is
+ loaded.</para>
</sect2>
</sect1>
@@ -515,18 +489,18 @@ pcm7: &lt;HDA Realtek ALC889 PCM #3 Digital&gt; at cad 2 nid 1 on hdac1
<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>
+ <para>This section describes some <acronym>MP3</acronym>
+ players available for &os;, how to rip audio CD tracks, and
+ how to encode and decode <acronym>MP3</acronym>s.</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).
+ <para>A popular graphical <acronym>MP3</acronym> player is
+ <application>XMMS</application>.
<application>Winamp</application>
skins can be used with <application>XMMS</application> since
- the GUI is almost identical to that of Nullsoft's
+ the interface is almost identical to that of Nullsoft's
<application>Winamp</application>.
<application>XMMS</application> also has native plug-in
support.</para>
@@ -541,14 +515,16 @@ pcm7: &lt;HDA Realtek ALC889 PCM #3 Digital&gt; at cad 2 nid 1 on hdac1
<application>XMMS</application> simple to use.</para>
<para>The <filename role="package">audio/mpg123</filename> port
- is an alternative, command-line MP3 player.</para>
+ provides an alternative, command-line <acronym>MP3</acronym>
+ 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>
+ the sound device and the <acronym>MP3</acronym> file on the
+ command line. Assuming the audio device is
+ <devicename>/dev/dsp1.0</devicename> and the
+ <acronym>MP3</acronym> file is
+ <replaceable>Foobar-GreatestHits.mp3</replaceable>, enter the
+ following to play the file:</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.
@@ -567,63 +543,64 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen>
<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>Before encoding a CD or CD track to
+ <acronym>MP3</acronym>, the audio data on the CD must be
+ ripped to the hard drive. This is done by copying the raw CD
+ Digital Audio (<acronym>CDDA</acronym>) data to
+ <acronym>WAV</acronym> files.</para>
- <para>The <command>cdda2wav</command> tool, which is a part of
- the <filename role="package">sysutils/cdrtools</filename>
+ <para>The <command>cdda2wav</command> tool, which is installed
+ with 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>
+ be issued as <username>root</username> to rip an entire CD
+ into individual (per track) <acronym>WAV</acronym>
+ 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><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>To rip individual tracks, make use of the
- <option>-t</option> option as shown:</para>
+ <option>-t</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
+ a range of tracks, such as 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>
+ <para>&man.dd.1; can also be used to extract audio tracks on
+ ATAPI drives, as described in <xref
+ linkend="duplicating-audiocds"/>.</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>
+ <application>Lame</application> is a popular
+ <acronym>MP3</acronym> encoder which can be installed from the
+ <filename role="package">audio/lame</filename> port. Due to
+ licensing restrictions, a package is not available.</para>
- <para>Using the ripped WAV files, the following command will
- convert
+ <para>The following command will convert the ripped
+ <acronym>WAV</acronym> files
<filename><replaceable>audio01.wav</replaceable></filename>
to
<filename><replaceable>audio01.mp3</replaceable></filename>:</para>
@@ -637,26 +614,27 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen>
--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>
+ <para>128&nbsp;kbits is a standard <acronym>MP3</acronym>
+ bitrate. The 160 and 192 bitrates provide higher quality.
+ The higher the bitrate, the larger the size of the resulting
+ <acronym>MP3</acronym>. <option>-h</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 <acronym>MP3</acronym> file. Additional encoding options
+ can be found in the <application>lame</application> manual
+ 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
+ <para>In order to burn an audio CD from <acronym>MP3</acronym>s,
+ they must first be converted to a non-compressed
+ <acronym>WAV</acronym> format. Both
<application>XMMS</application> and
- <application>mpg123</application> support the output of MP3
- to an uncompressed file format.</para>
+ <application>mpg123</application> support the output of
+ <acronym>MP3</acronym> to an uncompressed file format.</para>
<para>Writing to Disk in <application>XMMS</application>:</para>
@@ -666,12 +644,12 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen>
</step>
<step>
- <para>Right-click on the window to bring up the
+ <para>Right-click the window to bring up the
<application>XMMS</application> menu.</para>
</step>
<step>
- <para>Select <literal>Preference</literal> under
+ <para>Select <literal>Preferences</literal> under
<literal>Options</literal>.</para>
</step>
@@ -685,26 +663,28 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen>
</step>
<step>
- <para>Enter (or choose browse) a directory to write the
+ <para>Enter or browse to 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>
+ <para>Load the <acronym>MP3</acronym> 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;
+ <para>Press <literal>Play</literal>. The
<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>
+ playing the <acronym>MP3</acronym>, but no music will be
+ heard. It is actually playing the <acronym>MP3</acronym>
+ 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>
+ <para>When finished, be sure to set the default Output
+ Plugin back to what it was before in order to listen to
+ <acronym>MP3</acronym>s again.</para>
</step>
</procedure>
@@ -719,22 +699,24 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen>
</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
+ <para><application>XMMS</application> writes a file in the
+ <acronym>WAV</acronym> format, while
+ <application>mpg123</application> converts the
+ <acronym>MP3</acronym> into raw PCM audio data. Both of these
+ formats can be used with <application>cdrecord</application>
+ to create audio CDs, whereas &man.burncd.8; requires a raw
+ Pulse-Code Modulation (<acronym>PCM</acronym>. When using
+ <acronym>WAV</acronym> files, there will be a small tick
+ sound at the beginning of each track. This sound is the
+ header of the <acronym>WAV</acronym> file. One can remove the
+ header with <application>SoX</application>, which can be
installed from the <filename
- role="package">audio/sox</filename> port or package):</para>
+ 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>
+ <para>Refer to <xref linkend="creating-cds"/> for more
+ information on using a CD burner in &os;.</para>
</sect2>
</sect1>
@@ -752,43 +734,40 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen>
<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
+ <para>Before configuring video playback, determine the model
+ of the video card 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
+ a list of extensions supported by the
+ <application>&xorg;</application> server using the card, run
+ &man.xdpyinfo.1; while <application>&xorg;</application> is
+ running.</para>
+
+ <para>It is a good idea to have a short MPEG test file for
+ evaluating various players and options. Since some DVD
+ applications look for DVD media in <filename
+ class="directory">/dev/dvd</filename> by default, or have this
+ device name hardcoded in them, it might be 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>
+ <para>Due to the nature of &man.devfs.5;, manually created links
+ will not persist after a system reboot. In order to create the
+ symbolic links automatically when the system boots, 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>DVD decryption invokes special DVD-ROM functions and
+ 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>
+ <para>To enhance the shared memory
+ <application>&xorg;</application> interface, it is
+ recommended to increase the values of these &man.sysctl.8;
+ variables:</para>
<programlisting>kern.ipc.shmmax=67108864
kern.ipc.shmall=32768</programlisting>
@@ -800,32 +779,33 @@ kern.ipc.shmall=32768</programlisting>
<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>There are several possible ways to display video under
+ <application>&xorg;</application>. What works is largely
+ hardware dependent. Each method described below will have
+ varying quality across different hardware.</para>
- <para>A list of common video interfaces:</para>
+ <para>Common video interfaces include:</para>
<orderedlist>
<listitem>
- <para>X11: normal X11 output using shared memory.</para>
+ <para><application>&xorg;</application>: normal output using
+ shared memory.</para>
</listitem>
<listitem>
- <para>XVideo: an extension to the X11 interface which supports
- video in any X11 drawable.</para>
+ <para>XVideo: an extension to the
+ <application>&xorg;</application> interface which supports
+ video in any drawable object.</para>
</listitem>
<listitem>
- <para>SDL: the Simple Directmedia Layer.</para>
+ <para><acronym>SDL</acronym>: the Simple Directmedia
+ Layer.</para>
</listitem>
<listitem>
- <para>DGA: the Direct Graphics Access.</para>
+ <para><acronym>DGA</acronym>: the Direct Graphics
+ Access.</para>
</listitem>
<listitem>
@@ -837,9 +817,9 @@ kern.ipc.shmall=32768</programlisting>
<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
+ <emphasis>XVideo</emphasis>, also known as Xvideo, Xv, and xv.
+ It allows video to be directly displayed in drawable objects
+ through a special acceleration. This extension provides
good quality playback even on low-end machines.</para>
<para>To check whether the extension is running, use
@@ -847,7 +827,7 @@ kern.ipc.shmall=32768</programlisting>
<screen>&prompt.user; <userinput>xvinfo</userinput></screen>
- <para>XVideo is supported for your card if the result looks
+ <para>XVideo is supported for the card if the result looks
like:</para>
<screen>X-Video Extension version 2.2
@@ -919,9 +899,9 @@ kern.ipc.shmall=32768</programlisting>
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>The formats listed, such as YUV2 and YUV12, are not present
+ with every implementation of XVideo and their absence may hinder
+ some players.</para>
<para>If the result looks like:</para>
@@ -929,15 +909,11 @@ kern.ipc.shmall=32768</programlisting>
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>
+ <para>XVideo is probably not supported for the card. This means
+ that it will be more difficult for the display to meet the
+ computational demands of rendering video. Depending on the
+ video card and processor, one might still be able to have a
+ satisfying experience.</para>
</sect3>
@@ -949,26 +925,28 @@ no adaptors present</screen>
allowing cross-platform applications to be developed which make
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>
+ more efficient than the <application>&xorg;</application>
+ interface.</para>
- <para>The SDL can be found at <filename
- role="package">devel/sdl12</filename>.</para>
+ <para><acronym>SDL</acronym> can be installed using the <filename
+ role="package">devel/sdl12</filename> package or port.</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
+ <para><acronym>DGA</acronym> is an
+ <application>&xorg;</application> extension which allows a
+ program to bypass the <application>&xorg;</application> server
+ and directly alter the framebuffer. Because it relies on a low
+ level memory mapping, 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>
+ <para>The <acronym>DGA</acronym> extension can be tested and
+ benchmarked using &man.dga.1;. When <command>dga</command> is
+ running, it changes the colors of the display whenever a key is
+ pressed. To quit, press <keycap>q</keycap>.</para>
</sect3>
</sect2>
@@ -979,17 +957,14 @@ no adaptors present</screen>
<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>This section introduces some of the software available from
+ the &os; Ports Collection which can be used for video
+ playback.</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>
+ <para>Many of the video applications which run on &os; were
+ developed as &linux; applications. Many of these applications
+ are still beta-quality. Some of the problems commonly
+ encountered with video packages on &os; include:</para>
<orderedlist>
@@ -1010,8 +985,8 @@ no adaptors present</screen>
</listitem>
<listitem>
- <para>A seemingly trivial filter like rescaling of the image
- size results in very bad artifacts from a buggy rescaling
+ <para>A seemingly trivial filter, like rescaling of the image
+ size, results in bad artifacts from a buggy rescaling
routine.</para>
</listitem>
@@ -1028,14 +1003,13 @@ no adaptors present</screen>
</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>
+ <para>Many applications may also exhibit
+ <quote>&linux;-isms</quote>. 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>
@@ -1049,29 +1023,19 @@ no adaptors present</screen>
</listitem>
<listitem>
- <para>Software not yet in the FreeBSD Ports Collection
- which is commonly used in conjunction with the
- application.</para>
+ <para>Relies on software which is not yet available in the
+ &os; Ports Collection.</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>
+ <para><application>MPlayer</application> is a command-line video
+ player with an optional graphical interface which aims to
+ provide speed and flexibility. This application, as well as
+ other graphical front-ends, is available from the &os; Ports
+ Collection.</para>
<sect4 id="video-mplayer-building">
<title>Building MPlayer</title>
@@ -1079,54 +1043,33 @@ no adaptors present</screen>
<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>
+ <para><application>MPlayer</application> is available as a
+ package or port in <filename
+ role="package">multimedia/mplayer</filename>. Several
+ compile options are available and a variety of hardware
+ checks occur during the build process. For these reasons,
+ some users prefer to build the port rather than install the
+ package. The available options will be displayed in a
+ menu after these commands are input:</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>
+&prompt.root; <userinput>make</userinput></screen>
+
+ <para>The menu options should be reviewed to determine the
+ type of support to compile into the port. If an option is
+ not selected, <application>MPlayer</application> will not be
+ able to display that type of video format. Use the arrow
+ keys and spacebar to select the required formats. When
+ finished, press <keycap>Enter</keycap> to continue the port
+ compile and installation.</para>
+
+ <para>By default, this package or port will build the
+ <command>mplayer</command> command line utility and the
+ <command>gmplayer</command> graphical utility. To encode
+ videos, install the <filename
+ role="package">multimedia/mencoder</filename> port. Due
+ to licensing restrictions, a package is not available for
+ <command>MEncoder</command>.</para>
</sect4>
@@ -1136,23 +1079,20 @@ http://www.mplayerhq.hu/homepage/dload.html</screen>
<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 first time <application>MPlayer</application> is
+ run, it will create <filename
+ class="directory">~/.mplayer</filename> in the user's
+ home directory. This subdirectory contains default versions
+ of the user-specific configuration files.</para>
- <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>This section describes only a few common uses. Refer
+ to the <command>mplayer</command> manual page for a complete
+ description of its numerous options.</para>
- <para>To play a file, such as
+ <para>To play the file
<filename><replaceable>testfile.avi</replaceable></filename>,
- through one of the various video interfaces set the
- <option>-vo</option> option:</para>
+ specify the video interfaces with
+ <option>-vo</option>:</para>
<screen>&prompt.user; <userinput>mplayer -vo xv <replaceable>testfile.avi</replaceable></userinput></screen>
@@ -1168,46 +1108,47 @@ http://www.mplayerhq.hu/homepage/dload.html</screen>
relative performance depends on many factors and will vary
significantly with hardware.</para>
- <para>To play from a DVD, replace the
+ <para>To play a DVD, replace the
<filename><replaceable>testfile.avi</replaceable></filename>
with <option>dvd://<replaceable>N</replaceable> -dvd-device
- <replaceable>DEVICE</replaceable></option> where
+ <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>
+ title 3 from <devicename>/dev/dvd</devicename>:</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>
+ of the <application>MPlayer</application> port by
+ including the
+ <makevar>WITH_DVD_DEVICE=/path/to/desired/device</makevar>
+ option. By default, the device is
+ <filename>/dev/acd0</filename>. More details can be found
+ in the port's
+ <filename>Makefile.options</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>To stop, pause, advance, and so on, consult the
+ keybindings, which are displayed 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
+ <para>Additional playback options include
+ <option>-fs -zoom</option>, which engages 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>
+ <para>Each user can add commonly used options to their
+ <filename>~/.mplayer/config</filename> like so:</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>
+ <para><command>mplayer</command> can be used to rip a DVD
+ title to a <filename>.vob</filename>. To dump the second
+ title from a DVD:</para>
<screen>&prompt.root; <userinput>mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd</userinput></screen>
@@ -1215,87 +1156,86 @@ zoom=yes</programlisting>
MPEG and can be manipulated by the other packages described
in this section.</para>
+ <para>The <ulink url="http://www.mplayerhq.hu/DOCS/">MPlayer
+ documentation</ulink> is technically informative and
+ should 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
+ before making a bug report, read the documentation
+ first.</para>
+
</sect4>
<sect4 id="video-mencoder">
- <title>mencoder</title>
+ <title><application>MEncoder</application></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>
+ <para>Before using <command>mencoder</command>, it is a good
+ idea to become familiar with the options described in the
+ <ulink
+ url="http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html">HTML
+ documentation</ulink>. There are innumerable ways to
+ improve quality, lower bitrate, and change formats, and some
+ of these options may make the difference between good or bad
+ performance. Improper combinations of command line options
+ can yield output files that are unplayable even by
+ <command>mplayer</command>.</para>
+
+ <para>Here is an example of 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
+ <para>To rip to a file, use <option>-dumpfile</option> with
<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>
+ to the MPEG4 codec with MPEG3 audio encoding, first install
+ the <filename role="package">audio/lame</filename> port.
+ Due to licensing restrictions, a package is not available.
+ Once installed, type:</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
+ <para>This will produce output playable by applications such
+ as <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>
+ to re-encode a DVD title directly. Since it may take a few
+ tries to get the desired result, it is recommended to dump
+ the title to a file and to 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>
+ <title>The <application>xine</application> Video Player</title>
+
+ <para><application>xine</application> is a video player with a
+ reusable base library and a modular executable which can be
+ extended with plugins. It can be installed using the
+ <filename role="package">multimedia/xine</filename> package or
+ port.</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
+ <para>In practice, <application>xine</application> requires
+ either a fast CPU with a fast video card, or support for the
+ XVideo extension. 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>
+ <para>By default, the <application>xine</application> player
+ starts a graphical user interface. The menus can then be used
+ to open a specific file.</para>
+
+ <para>Alternatively, <application>xine</application> may be
+ invoked to play a file immediately without the graphical
+ interface:</para>
<screen>&prompt.user; <userinput>xine</userinput></screen>
@@ -1304,33 +1244,37 @@ zoom=yes</programlisting>
<screen>&prompt.user; <userinput>xine -g -p <replaceable>mymovie.avi</replaceable></userinput></screen>
+ <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>
</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>
+ <title>The <application>transcode</application>
+ Utilities</title>
+
+ <para><application>transcode</application> provides a suite of
+ tools for re-encoding video and audio files.
+ <application>transcode</application> can be used to merge
+ video files or repair broken files using command line tools
+ with <filename>stdin/stdout</filename> stream
+ interfaces.</para>
+
+ <para><application>transcode</application> can be installed
+ using the <filename
+ role="package">multimedia/transcode</filename> package or
+ port. Many users prefer to compile the port as it provides a
+ menu of compile options for specifying the support and codecs
+ to compile in. If an option is not selected,
+ <application>transcode</application> will not be able to
+ encode that format. Use the arrow keys and spacebar to select
+ the required formats. When finished, press
+ <keycap>Enter</keycap> to continue the port compile and
+ installation.</para>
+
+ <para>This example demonstrates 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>
@@ -1339,75 +1283,17 @@ WITH_MJPEG=yes -DWITH_XVID=yes</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
+ The file can be burned on a CD-R media to create a Video CD. In
+ this, install and use the <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
+ <para>In addition to the manual page for
+ <command>transcode</command>, refer to 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">
@@ -1438,44 +1324,43 @@ WITH_MJPEG=yes -DWITH_XVID=yes</userinput></screen>
<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>TV cards allow can be used to watch broadcast or cable TV on
+ a computer. Most cards accept composite video via an RCA or
+ S-video input and some cards include 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>
+ video capture chip with the &man.bktr.4; driver. Ensure the
+ board comes with a supported tuner. Consult &man.bktr.4; for a
+ list of supported tuners.</para>
</sect2>
<sect2>
- <title>Adding the Driver</title>
+ <title>Loading 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>
+ <para>In order to use the card, the &man.bktr.4; driver must be
+ loaded. To automate this at boot time, add the following line
+ to <filename>/boot/loader.conf</filename>:</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>
+ <para>Alternatively, one can statically compile support for
+ the TV card into a custom kernel. In that case, add the
+ following lines to the custom kernel configuration
+ file:</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>These additional devices are necessary as the card
+ components are 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>
+ <para>To test the driver, reboot the system. The TV card
+ should appear in the boot messages, as seen in this
+ example:</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
@@ -1484,30 +1369,30 @@ 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>
+ <para>The messages will differ according to the hardware. Check
+ the messages to determine 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, to force the tuner to a Philips
+ SECAM tuner, add the following line to a custom kernel
+ configuration file:</para>
<programlisting>options OVERRIDE_TUNER=6</programlisting>
- <para>or you can directly use &man.sysctl.8;:</para>
+ <para>or, 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
+ <para>Refer to &man.bktr.4; and
+ <filename>/usr/src/sys/conf/NOTES</filename> 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>
+ <para>To use the TV card, install one of the following
+ applications:</para>
<itemizedlist>
<listitem>
@@ -1517,21 +1402,12 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting>
</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>
+ is another TV application with similar features.</para>
</listitem>
<listitem>
- <para><filename role="package">audio/wmtune</filename>, a
- handy desktop application for radio tuners.</para>
+ <para><filename role="package">audio/xmradio</filename>
+ provides an application for using the FM radio tuner of a
+ TV card.</para>
</listitem>
</itemizedlist>
@@ -1542,92 +1418,85 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting>
<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>
+ <para>If any problems are encountered with the TV card,
+ check that the video capture chip and the tuner are
+ supported by &man.bktr.4; and that the right configuration
+ options were used. For more support and various questions
+ about TV cards, refer to 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>MythTV is a popular, open source <acronym
+ role="Personal Video Recorder">PVR</acronym>
+ application. This section demonstrates how to install and
+ setup MythTV on &os;. Refer to the <ulink
+ url="http://www.mythtv.org/wiki/">MythTV wiki</ulink> for
+ more information on how to use MythTV.</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>
+ <para>MythTV requires a frontend and a backend; however,
+ it 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,
+ along with the &mysql; database server. Optionally a tuner
+ and storage for any recorded data. The &mysql; package should
+ be automatically installed as a dependency when installing
+ <filename role="package">multimedia/mythtv</filename>.</para>
<sect2>
<title>Hardware</title>
- <para>MythTV is designed to utilise <acronym
+ <para>MythTV is designed to utilize <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="package">multimedia/webcamd</filename>, as it 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
+ work with MythTV. 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
+ Drivers are also available for Hauppauge cards in the
+ following ports: <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>
+ with versions of MythTV greater than 0.23. Due to licensing
+ restrictions, no packages are available and these two ports
+ must be compiled.</para>
- <para><ulink url="http://wiki.freebsd.org/HTPC">HTPC</ulink>
- contains a list of all available <acronym
+ <para>The <ulink url="http://wiki.freebsd.org/HTPC">HTPC
+ wiki page</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>
+ <para>To install the MythTV port:</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>
+ <para>Once installed, set up the MythTV database:</para>
<screen>&prompt.root; <userinput>mysql -uroot -p &lt; /usr/local/share/mythtv/database/mc.sql</userinput></screen>
@@ -1637,7 +1506,7 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting>
<para>Start the backend:</para>
- <screen>&prompt.root; <userinput>echo 'mythbackend_enable="YES"' >> /etc/rc.conf</userinput>
+ <screen>&prompt.root; <userinput>echo 'mythbackend_enable="YES"' &gt;&gt; /etc/rc.conf</userinput>
&prompt.root; <userinput>service mythbackend start</userinput></screen>
</sect2>
</sect1>
@@ -1660,40 +1529,35 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting>
<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.</para>
- </sect2>
+ <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 provide access to the scanner
+ hardware.</para>
+
+ <para>&os; supports both SCSI and USB scanners. Be sure the
+ scanner is supported by <application>SANE</application> prior
+ to performing any configuration. Refer to the <ulink
+ url="http://www.sane-project.org/sane-supported-devices.html">
+ supported devices list</ulink> for more information about supported
+ scanners.</para>
<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>
+ <para>Both SCSI and USB interfaces are supported. Depending
+ upon the 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
+ Users with a custom kernel should ensure that the following
+ lines are present in the custom kernel configuration
file:</para>
<programlisting>device usb
@@ -1701,47 +1565,43 @@ device uhci
device ohci
device ehci</programlisting>
- <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>
+ <para>Plug in the USB scanner. Use &man.dmesg.8; to determine
+ whether the scanner appears in the system message
+ buffer:</para>
<screen>ugen0.2: &lt;EPSON&gt; at usbus0</screen>
- <para>These messages show that our scanner is using
- either <filename>/dev/ugen0.2</filename>
- as device node. For this example, a
+ <para>These messages indicate that the scanner is using
+ either <filename>/dev/ugen0.2</filename> or
+ <filename>/dev/uscanner0</filename>, depending on the &os;
+ version. 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>
+ <para>If the scanner uses a SCSI interface, it is important to
+ know which SCSI controller board it will use. Depending
+ upon the SCSI chipset, a custom kernel configuration file
+ may be needed. The <filename>GENERIC</filename> kernel
+ supports the most common SCSI controllers. Refer to
+ <filename>/usr/src/sys/conf/NOTES</filename> to determine
+ the correct line to add to a custom kernel configuration
+ file. In addition to the SCSI adapter driver, the following
+ lines are needed in the 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>
+ <para>Verify that the device is displayed in the system
+ message buffer:</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
+ <para>If the 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>
@@ -1752,7 +1612,7 @@ 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
+ <para>The scanner should now appear in the SCSI devices
list:</para>
<screen>&prompt.root; <userinput>camcontrol devlist</userinput>
@@ -1761,97 +1621,81 @@ Re-scan of bus 3 was successful</screen>
&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>
+ <para>Refer to &man.scsi.4; and &man.camcontrol.8; for more
+ details about SCSI devices on &os;.</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
+ <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
+ role="package">graphics/sane-frontends</filename>). The
+ backends provide access to the scanner. 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
+ url="http://www.sane-project.org/sane-supported-devices.html">supported
+ devices</ulink> list specifies which backend will support the
+ image scanner. The correct backend is needed in order to use
+ the scanner. The frontends provide the graphical scanning
+ interface, <application>xscanimage</application>.</para>
+
+ <para>After installing 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
+ package, use <command>sane-find-scanner</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>
+ <para>The output should 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 or may not appear.</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>
+ <para>Some USB scanners require firmware to be loaded. Refer
+ to &man.sane-find-scanner.1; and &man.sane.7; for
+ details.</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>
+ <para>Next, check if the scanner will be identified by a
+ scanning frontend. By default, the
+ <application>SANE</application> backends come with a command
+ line tool called &man.scanimage.1;. This command can be used
+ to list the devices and perform an image acquisition. Use
+ <option>-L</option> 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
+ <para>Here is the output for the USB scanner used in <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
+ <para>In this output,
+ <literal>'epson2:libusb:/dev/usb:/dev/ugen0.2'</literal> is
+ the backend name (<literal>epson2</literal>) and the device
+ node (<literal>/dev/ugen0.2</literal>) used by the
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
+ identify the scanner. If this happens, edit the backend
+ configuration file in <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>
+ and define the scanner device used.</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>
+ <para>In the above example, the USB scanner is perfectly
+ detected and working.</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>
+ <para>To determine if the scanner is correctly
+ identified:</para>
<screen>&prompt.root; <userinput>scanimage -L</userinput>
@@ -1860,108 +1704,94 @@ 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
+ <para>Since the scanner is not identified, edit
+ <filename>/usr/local/etc/sane.d/epson2.conf</filename>. In
+ this example, the scanner model is
+ &epson.perfection;&nbsp;1650 and it uses the
+ <literal>epson2</literal> backend. When editing, read the
+ help comments in the backend configuration file. Line
+ changes are simple: comment out all lines that have the
+ wrong interface for the scanner. In this example, 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>
+ as the scanner uses the USB interface. Then, at the end
+ of the file, add a line specifying the interface and the
+ device node used. In this case, 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>
+ <para>Save the edits and verify that 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>
+ <para>The <literal>`epson:/dev/uscanner0'</literal> field now
+ gives the right backend name and the 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>
+ <para>Once <command>scanimage -L</command> sees the scanner, the
+ configuration is complete and the device is now ready to
+ scan.</para>
+
+ <para>While &man.scanimage.1; can be used to perform an image
+ acquisition from the command line, it is often preferable to
+ use a graphical interface to perform image scanning. The
+ <filename role="package">graphics/sane-frontends</filename>
+ package or port installs a simple but efficient graphical
+ interface, <application>xscanimage</application>.</para>
+
+ <para><application>Xsane</application>, which is installed with
+ the <filename role="package">graphics/xsane</filename> package
+ or port, is another popular graphical scanning frontend. It
+ offers advanced features such as various scanning modes, color
+ correction, and batch scans. 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
+ <para>In order to have access to the scanner, a user needs
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>
+ scanner. In the previous example, the USB scanner uses the
+ device node <filename>/dev/ugen0.2</filename> which is really a
+ symlink to the real device node
+ <filename>/dev/usb/0.2.0</filename>. The symlink and the device
+ node are owned, respectively, by the
+ <groupname>wheel</groupname> and
+ <groupname>operator</groupname> groups. Adding the user to
+ these groups will allow access to the scanner. However, for
+ security reasons, always think twice before adding a user
+ to any group, especially <groupname>wheel</groupname>. A better
+ solution is to create a group to make the scanner device
+ accessible to members of this group.</para>
+
+ <para>This example creates a group called
+ <groupname><replaceable>usb</replaceable></groupname> using
+ &man.pw.8;:</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>
+ <para>Then, 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 write
+ permissions of (<literal>0660</literal> or
+ <literal>0664</literal>. All of this is done by adding the
+ following lines to
+ <filename>/etc/devfs.rules</filename>:</para>
<programlisting>[system=5]
add path ugen0.2 mode 0660 group usb
add path usb/0.2.0 mode 0666 group usb</programlisting>
- <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>
+ <para>Finally, add the users to
+ <groupname><replaceable>usb</replaceable></groupname> in order
+ to allow 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>
+ <para>For more details refer to &man.pw.8;.</para>
</sect2>
</sect1>
</chapter>