Page MenuHomeFreeBSD
Files F102955913

D38798.diff
No OneTemporary
Actions

D38798.diff
View Options

diff --git a/documentation/content/en/books/handbook/multimedia/_index.adoc b/documentation/content/en/books/handbook/multimedia/_index.adoc
--- a/documentation/content/en/books/handbook/multimedia/_index.adoc
+++ b/documentation/content/en/books/handbook/multimedia/_index.adoc
@@ -3,8 +3,8 @@
part: Part II. Common Tasks
prev: books/handbook/desktop
next: books/handbook/kernelconfig
-description: FreeBSD supports a wide variety of sound cards, allowing users to enjoy high fidelity output from a FreeBSD system
-tags: ["multimedia", "sound card", "MP3", "MythTV", "scanner", "SANE"]
+description: The multimedia chapter provides an overview of multimedia support on FreeBSD
+tags: ["multimedia", "sound card", "Audio players", "scanner", "SANE", "Video players", "Conferencing and Meetings", "Setting Up the Webcam"]
showBookMenu: true
weight: 11
path: "/books/handbook/"
@@ -51,228 +51,196 @@
[[multimedia-synopsis]]
== Synopsis
-FreeBSD supports a wide variety of sound cards, allowing users to enjoy high fidelity output from a FreeBSD system.
-This includes the ability to record and play back audio in the MPEG Audio Layer 3 (`MP3`), Waveform Audio File (`WAV`), Ogg Vorbis, and other formats.
-The FreeBSD Ports Collection contains many applications for editing recorded audio, adding sound effects, and controlling attached MIDI devices.
-
-FreeBSD also supports the playback of video files and ``DVD``s.
-The FreeBSD Ports Collection contains applications to encode, convert, and playback various video media.
-
-This chapter describes how to configure sound cards, video playback, TV tuner cards, and scanners on FreeBSD.
-It also describes some of the applications which are available for using these devices.
-
-After reading this chapter, you will know how to:
-
-* Configure a sound card on FreeBSD.
-* Troubleshoot the sound setup.
-* Playback and encode MP3s and other audio.
-* Prepare a FreeBSD system for video playback.
-* Play ``DVD``s, [.filename]#.mpg#, and [.filename]#.avi# files.
-* Rip `CD` and `DVD` content into files.
-* Configure a TV card.
-* Install and setup MythTV on FreeBSD
-* Configure an image scanner.
-* Configure a Bluetooth headset.
-
-Before reading this chapter, you should:
-
-* Know how to install applications as described in crossref:ports[ports,Installing Applications: Packages and Ports].
+The multimedia chapter provides an overview of multimedia support on FreeBSD.
+Multimedia applications and technologies have become an integral part of modern computing, and FreeBSD provides robust and reliable support for a wide range of multimedia hardware and software.
+This chapter covers various multimedia components such as audio, video, and image processing.
+It also discusses various media formats and codecs, as well as tools and applications for multimedia creation and playback. Additionally, the chapter covers multimedia system configuration, troubleshooting, and optimization.
+Whether you are a multimedia enthusiast or a professional content creator, FreeBSD offers a robust platform for multimedia work.
+This chapter aims to help get the most out of FreeBSD's multimedia capabilities, providing useful information and practical examples to help get started
[[sound-setup]]
== Setting Up the Sound Card
-Before beginning the configuration, determine the model of the sound card and the chip it uses.
+By default, FreeBSD will automatically detect the sound card used by the system.
FreeBSD supports a wide variety of sound cards.
-Check the supported audio devices list of the link:{u-rel120-hardware}[Hardware Notes] to see if the card is supported and which FreeBSD driver it uses.
+The list of supported sound cards can be consulted in man:sound[4].
-In order to use the sound device, its device driver must be loaded.
-The easiest way is to load a kernel module for the sound card with man:kldload[8].
-This example loads the driver for a built-in audio chipset based on the Intel specification:
+[NOTE]
+====
+It is only necessary to load the sound card module in case FreeBSD has not detected it correctly.
+====
+
+In case of not knowing which sound card the system has or which module to use the `snd_driver` metadriver can be loaded executing the following command:
[source,shell]
....
-# kldload snd_hda
+# kldload snd_driver
....
-To automate the loading of this driver at boot time, add the driver to [.filename]#/boot/loader.conf#.
-The line for this driver is:
+Alternatively, to load the driver as a module at boot time, place the following line in [.filename]#/boot/loader.conf#:
[.programlisting]
....
-snd_hda_load="YES"
+snd_driver_load="YES"
....
-Other available sound modules are listed in [.filename]#/boot/defaults/loader.conf#.
-When unsure which driver to use, load the [.filename]#snd_driver# module:
+[[sound-testing]]
+=== Testing Sound
+
+To confirm the sound card is detected the following command can be executed:
[source,shell]
....
-# kldload snd_driver
+% dmesg | grep pcm
....
-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#.
-
-To determine which driver was selected for the sound card after loading the [.filename]#snd_driver# metadriver, type `cat /dev/sndstat`.
-
-=== Configuring a Custom Kernel with Sound Support
-
-This section is for users who prefer to statically compile in support for the sound card in a custom kernel.
-For more information about recompiling a kernel, refer to crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel].
-
-When using a custom kernel to provide sound support, make sure that the audio framework driver exists in the custom kernel configuration file:
+The output should be similar to the following:
[.programlisting]
....
-device sound
+pcm0: <Conexant CX20561 (Hermosa) (Analog 2.0+HP/2.0)> at nid 26,22 and 24 on hdaa0
+pcm1: <Conexant CX20561 (Hermosa) (Internal Analog Mic)> at nid 29 on hdaa0
....
-Next, add support for the sound card.
-To continue the example of the built-in audio chipset based on the Intel specification from the previous section, use the following line in the custom kernel configuration file:
+The status of the sound card may also be checked using this command:
-[.programlisting]
+[source,shell]
....
-device snd_hda
+# cat /dev/sndstat
....
-Be sure to read the manual page of the driver for the device name to use for the driver.
-
-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#.
-During the boot process, man:loader[8] reads this file and passes the settings to the kernel.
-For example, an old Creative SoundBlaster(R) 16 ISA non-PnP card will use the man:snd_sbc[4] driver in conjunction with `snd_sb16`.
-For this card, the following lines must be added to the kernel configuration file:
+The output should be similar to the following:
[.programlisting]
....
-device snd_sbc
-device snd_sb16
+Installed devices:
+pcm0: <Conexant CX20561 (Hermosa) (Analog 2.0+HP/2.0)> (play/rec) default
+pcm1: <Conexant CX20561 (Hermosa) (Internal Analog Mic)> (rec)
....
-If the card uses the `0x220` I/O port and IRQ `5`, these lines must also be added to [.filename]#/boot/device.hints#:
+If no `pcm` devices are listed, double-check that the correct device driver was loaded.
+If all goes well, the sound card should now work in FreeBSD.
-[.programlisting]
+man:beep[1] can be used to produce some noise, confirming that the sound card is working:
+
+[source,shell]
....
-hint.sbc.0.at="isa"
-hint.sbc.0.port="0x220"
-hint.sbc.0.irq="5"
-hint.sbc.0.drq="1"
-hint.sbc.0.flags="0x15"
+% beep
....
-The syntax used in [.filename]#/boot/device.hints# is described in man:sound[4] and the manual page for the driver of the sound card.
+[[sound-mixer]]
+=== Mixer
-The settings shown above are the defaults.
-In some 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.
+FreeBSD has different utilities to set/display sound card mixer values built on the FreeBSD Sound System:
-[[sound-testing]]
-=== Testing Sound
+.Supported mixer packages
+[options="header", cols="1,1,1,1"]
+|===
+| Name | License | Package | Toolkit
-After loading the required module or rebooting into the custom kernel, the sound card should be detected.
-To confirm, run `dmesg | grep pcm`.
-This example is from a system with a built-in Conexant CX20590 chipset:
+| man:mixer[8]
+| BSD-2
+| Included in base system
+| CLI
-[source,shell]
-....
-pcm0: <NVIDIA (0x001c) (HDMI/DP 8ch)> at nid 5 on hdaa0
-pcm1: <NVIDIA (0x001c) (HDMI/DP 8ch)> at nid 6 on hdaa0
-pcm2: <Conexant CX20590 (Analog 2.0+HP/2.0)> at nid 31,25 and 35,27 on hdaa1
-....
+| dsbmixer
+| BSD-2
+| package:audio/dsbmixer[]
+| Qt
-The status of the sound card may also be checked using this command:
+| KDE Plasma audio widget
+| GPL 2.0
+| package:audio/plasma5-plasma-pa[]
+| Qt
-[source,shell]
-....
-# cat /dev/sndstat
-FreeBSD Audio Driver (newpcm: 64bit 2009061500/amd64)
-Installed devices:
-pcm0: <NVIDIA (0x001c) (HDMI/DP 8ch)> (play)
-pcm1: <NVIDIA (0x001c) (HDMI/DP 8ch)> (play)
-pcm2: <Conexant CX20590 (Analog 2.0+HP/2.0)> (play/rec) default
-....
+| mixertui
+| BSD-2
+| package:audio/mixertui[]
+| TUI
+
+|===
-The output will vary depending upon the sound card.
-If no [.filename]#pcm# devices are listed, double-check that the correct device driver was loaded or compiled into the kernel.
-The next section lists some common problems and their solutions.
+[[graphics-card-sound]]
+=== Graphics Card Sound
-If all goes well, the sound card should now work in FreeBSD.
-If the `CD` or `DVD` drive is properly connected to the sound card, one can insert an audio `CD` in the drive and play it with man:cdcontrol[1]:
+Graphics cards often come with their own integrated sound devices, which may not be used as the default device.
+To confirm, run dmesg and look for the pcm entries:
+
+Identify how the system is enumerating the outputs executing the following command:
[source,shell]
....
-% cdcontrol -f /dev/acd0 play 1
+% dmesg | grep pcm
....
-[WARNING]
-====
-Audio ``CD``s have specialized encodings which means that they should not be mounted using man:mount[8].
-====
+The output looks something like this:
-Various applications, such as package:audio/workman[], provide a friendlier interface.
-The package:audio/mpg123[] port can be installed to listen to MP3 audio files.
+[.programlisting]
+....
+pcm0: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 0 nid 1 on hdac0
+pcm1: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 1 nid 1 on hdac0
+pcm2: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 2 nid 1 on hdac0
+pcm3: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 3 nid 1 on hdac0
+hdac1: HDA Codec #2: Realtek ALC889
+pcm4: <HDA Realtek ALC889 PCM #0 Analog> at cad 2 nid 1 on hdac1
+pcm5: <HDA Realtek ALC889 PCM #1 Analog> at cad 2 nid 1 on hdac1
+pcm6: <HDA Realtek ALC889 PCM #2 Digital> at cad 2 nid 1 on hdac1
+pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1
+....
-Another quick way to test the card is to send data to [.filename]#/dev/dsp#:
+The graphics card (NVIDIA(R)) has been enumerated before the sound card (Realtek(R)).
+This can be changed to use the sound card as the default device executing the following command:
[source,shell]
....
-% cat filename > /dev/dsp
+# sysctl hw.snd.default_unit=4
....
-where [.filename]#filename# can be any type of file.
-This command should produce some noise, confirming that the sound card is working.
-
-[NOTE]
-====
-The [.filename]#/dev/dsp*# 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].
-====
-
-[[bluetooth-headset]]
-=== Setting up Bluetooth Sound Devices
+To make this change permanent add the next line to [.filename]#/etc/sysctl.conf#:
-Connecting to a Bluetooth device is out of scope for this chapter.
-Refer to crossref:advanced-networking[network-bluetooth,“Bluetooth”] for more information.
-
-To get Bluetooth sound sink working with FreeBSD's sound system, users have to install package:audio/virtual_oss[] first:
-
-[source,shell]
+[.programlisting]
....
-# pkg install virtual_oss
+hw.snd.default_unit=4
....
-package:audio/virtual_oss[] requires `cuse` to be loaded into the kernel:
+[[automatically-switching-headphones]]
+=== Automatically Switching to Headphones
+
+Some systems may struggle with switching between audio outputs, fortunately FreeBSD allows for these to be specified in [.filename]#device.hints#, which can be configured for automatic switchover.
+
+Identify how the system is enumerating the audio outputs executing the following command:
[source,shell]
....
-# kldload cuse
+% dmesg | grep pcm
....
-To load `cuse` during system startup, run this command:
+The output looks something like this:
-[source,shell]
+[.programlisting]
....
-# echo 'cuse_load=yes' >> /boot/loader.conf
+pcm0: <Realtek ALC892 Analog> at nid 23 and 26 on hdaa0
+pcm1: <Realtek ALC892 Right Analog Headphones> at nid 22 on hdaa0
....
-To use headphones as a sound sink with package:audio/virtual_oss[], users need to create a virtual device after connecting to a Bluetooth audio device:
+Add the following lines to [.filename]#/boot/device.hints#:
-[source,shell]
+[.programlisting]
....
-# virtual_oss -C 2 -c 2 -r 48000 -b 16 -s 768 -R /dev/null -P /dev/bluetooth/headphones -d dsp
+hint.hdac.0.cad0.nid22.config="as=1 seq=15 device=Headphones"
+hint.hdac.0.cad0.nid26.config="as=2 seq=0 device=speakers"
....
[NOTE]
====
-_headphones_ in this example is a hostname from [.filename]#/etc/bluetooth/hosts#.
-`BT_ADDR` could be used instead.
+Keep in mind that these values are for the example indicated above.
+They may vary depending on the system.
====
-Refer to man:virtual_oss[8] for more information.
-
[[troubleshooting]]
=== Troubleshooting Sound
-<<multimedia-sound-common-error-messages>> lists some common error messages and their solutions:
+Some common error messages and their solutions:
[[multimedia-sound-common-error-messages]]
.Common Error Messages
@@ -281,70 +249,10 @@
| Error
| Solution
-|`sb_dspwr(XX) timed out`
-|
-
-The I/O port is not set correctly.
-
-|`bad irq XX`
-|
-
-The IRQ is set incorrectly. Make sure that the set IRQ and the sound IRQ are the same.
-
-|`xxx: gus pcm not attached, out of memory`
-|
-
-There is not enough available memory to use the device.
-
|`xxx: can't open /dev/dsp!`
-|
-
-Type `fstat \| grep dsp` to check if another application is holding the device open. Noteworthy troublemakers are esound and KDE's sound support.
+|Type `fstat \| grep dsp` to check if another application is holding the device open. Noteworthy troublemakers are esound and KDE's sound support.
|===
-Modern graphics cards often come with their own sound driver for use with `HDMI`.
-This sound device is sometimes enumerated before the sound card meaning that the sound card will not be used as the default playback device.
-To check if this is the case, run dmesg and look for `pcm`.
-The output looks something like this:
-
-[.programlisting]
-....
-...
-hdac0: HDA Driver Revision: 20100226_0142
-hdac1: HDA Driver Revision: 20100226_0142
-hdac0: HDA Codec #0: NVidia (Unknown)
-hdac0: HDA Codec #1: NVidia (Unknown)
-hdac0: HDA Codec #2: NVidia (Unknown)
-hdac0: HDA Codec #3: NVidia (Unknown)
-pcm0: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 0 nid 1 on hdac0
-pcm1: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 1 nid 1 on hdac0
-pcm2: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 2 nid 1 on hdac0
-pcm3: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 3 nid 1 on hdac0
-hdac1: HDA Codec #2: Realtek ALC889
-pcm4: <HDA Realtek ALC889 PCM #0 Analog> at cad 2 nid 1 on hdac1
-pcm5: <HDA Realtek ALC889 PCM #1 Analog> at cad 2 nid 1 on hdac1
-pcm6: <HDA Realtek ALC889 PCM #2 Digital> at cad 2 nid 1 on hdac1
-pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1
-...
-....
-
-In this example, the graphics card (`NVidia`) has been enumerated before the sound card (`Realtek ALC889`).
-To use the sound card as the default playback device, change `hw.snd.default_unit` to the unit that should be used for playback:
-
-[source,shell]
-....
-# sysctl hw.snd.default_unit=n
-....
-
-where `n` is the number of the sound device to use.
-In this example, it should be `4`.
-Make this change permanent by adding the following line to [.filename]#/etc/sysctl.conf#:
-
-[.programlisting]
-....
-hw.snd.default_unit=4
-....
-
Programs using package:audio/pulseaudio[] might need to restart the
package:audio/pulseaudio[] daemon for the changes in `hw.snd.default_unit` to
take effect.
@@ -373,877 +281,490 @@
the package:audio/pulseaudio[] daemon. Use kbd:[Ctrl+D] instead.
====
-[[sound-multiple-sources]]
-=== Utilizing Multiple Sound Sources
-
-It is often desirable to have multiple sources of sound that are able to play simultaneously.
-FreeBSD uses "Virtual Sound Channels" to multiplex the sound card's playback by mixing sound in the kernel.
+[[audio-ports]]
+== Audio players
-Three man:sysctl[8] knobs are available for configuring virtual channels:
+This section introduces some of the software available from the FreeBSD Ports Collection which can be used for audio playback.
-[source,shell]
-....
-# sysctl dev.pcm.0.play.vchans=4
-# sysctl dev.pcm.0.rec.vchans=4
-# sysctl hw.snd.maxautovchans=4
-....
-
-This example allocates four virtual channels, which is a practical number for everyday use.
-Both `dev.pcm.0.play.vchans=4` and `dev.pcm.0.rec.vchans=4` are configurable after a device has been attached and represent the number of virtual channels [.filename]#pcm0# has for playback and recording.
-Since the [.filename]#pcm# module can be loaded independently of the hardware drivers, `hw.snd.maxautovchans` indicates how many virtual channels will be given to an audio device when it is attached.
-Refer to man:pcm[4] for more information.
-
-[NOTE]
-====
-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.
-====
+.Audio players packages
+[options="header", cols="1,1,1,1"]
+|===
+| Name | License | Package | Toolkit
-The correct [.filename]#pcm# device will automatically be allocated transparently to a program that requests [.filename]#/dev/dsp0#.
+| Elisa
+| LGPL 3.0
+| package:audio/elisa[]
+| Qt
-=== Setting Default Values for Mixer Channels
+| GNOME Music
+| GPL 2.0
+| package:audio/gnome-music[]
+| GTK+
-The default values for the different mixer channels are hardcoded in the source code of the man:pcm[4] driver.
-While sound card mixer levels can be changed using man:mixer[8] or third-party applications and daemons, this is not a permanent solution.
-To instead set default mixer values at the driver level, define the appropriate values in [.filename]#/boot/device.hints#, as seen in this example:
+| Audacious
+| BSD-2
+| package:multimedia/audacious[]
+| Qt
-[.programlisting]
-....
-hint.pcm.0.vol="50"
-....
+| MOC (music on console)
+| GPL 2.0
+| package:audio/moc[]
+| TUI
-This will set the volume channel to a default value of `50` when the man:pcm[4] module is loaded.
-
-[[sound-mp3]]
-== MP3 Audio
-
-This section describes some `MP3` players available for FreeBSD, how to rip audio `CD` tracks, and how to encode and decode ``MP3``s.
+|===
-[[mp3-players]]
-=== MP3 Players
+[[elisa]]
+=== Elisa
-A popular graphical `MP3` player is Audacious.
-It supports Winamp skins and additional plugins.
-The interface is intuitive, with a playlist, graphic equalizer, and more.
-Those familiar with Winamp will find Audacious simple to use.
-On FreeBSD, Audacious can be installed from the package:multimedia/audacious[] port or package.
-Audacious is a descendant of XMMS.
+Elisa is a music player developed by the KDE community that strives to be simple and nice to use.
-The package:audio/mpg123[] package or port provides an alternative, command-line `MP3` player.
-Once installed, specify the `MP3` file to play on the command line.
-If the system has multiple audio devices, the sound device can also be specified:
+To install Elisa, execute:
[source,shell]
....
-# mpg123 -a /dev/dsp1.0 Foobar-GreatestHits.mp3
-High Performance MPEG 1.0/2.0/2.5 Audio Player for Layers 1, 2 and 3
- version 1.18.1; written and copyright by Michael Hipp and others
- free software (LGPL) without any warranty but with best wishes
-
-Playing MPEG stream from Foobar-GreatestHits.mp3 ...
-MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo
+# pkg install elisa
....
-Additional `MP3` players are available in the FreeBSD Ports Collection.
-
-[[rip-cd]]
-=== Ripping `CD` Audio Tracks
-
-Before encoding a `CD` or `CD` track to `MP3`, the audio data on the `CD` must be ripped to the hard drive.
-This is done by copying the raw `CD` Digital Audio (`CDDA`) data to `WAV` files.
+[[gnome-music]]
+=== GNOME Music
-The `cdda2wav` tool, which is installed with the package:sysutils/cdrtools[] suite, can be used to rip audio information from ``CD``s.
+Music is the new GNOME music playing application.
+It aims to combine an elegant and immersive browsing experience with simple and straightforward controls.
-With the audio `CD` in the drive, the following command can be issued as `root` to rip an entire `CD` into individual, per track, `WAV` files:
+To install GNOME Music, execute:
[source,shell]
....
-# cdda2wav -D 0,1,0 -B
+# pkg install gnome-music
....
-In this example, the `-D _0,1,0_` indicates the `SCSI` device [.filename]#0,1,0# containing the `CD` to rip.
-Use `cdrecord -scanbus` to determine the correct device parameters for the system.
+[[audacious]]
+=== Audacious
-To rip individual tracks, use `-t` to specify the track:
+Audacious is an open source audio player.
+A descendant of XMMS, it plays your music how you want it, without stealing away your computer's resources from other tasks.
-[source,shell]
-....
-# cdda2wav -D 0,1,0 -t 7
-....
-
-To rip a range of tracks, such as track one to seven, specify a range:
+To install Audacious, execute:
[source,shell]
....
-# cdda2wav -D 0,1,0 -t 1+7
+# pkg install audacious-qt6 audacious-plugins-qt6
....
-To rip from an `ATAPI` (`IDE`) `CDROM` drive, specify the device name in place of the `SCSI` unit numbers.
-For example, to rip track 7 from an IDE drive:
-
-[source,shell]
-....
-# cdda2wav -D /dev/acd0 -t 7
-....
+[NOTE]
+====
+Audacious supports OSS natively, but must be configured in the settings on the Audio tab.
+====
-Alternately, `dd` can be used to extract audio tracks on `ATAPI` drives, as described in crossref:disks[duplicating-audiocds,“Duplicating Audio CDs”].
+[[moc-music-on-console]]
+=== MOC (music on console)
-[[mp3-encoding]]
-=== Encoding and Decoding MP3s
+MOC (music on console) is a console audio player designed to be powerful and easy to use.
-Lame is a popular `MP3` encoder which can be installed from the package:audio/lame[] port.
-Due to patent issues, a package is not available.
+MOC plays smoothly, regardless of system or I/O load, because it handles the output buffer in a separate thread.
+It does not cause gaps between files, because the next file to be played is pre-cached while playing the current file.
-The following command will convert the ripped `WAV` file [.filename]#audio01.wav# to [.filename]#audio01.mp3#:
+To install MOC (music on console), execute:
[source,shell]
....
-# lame -h -b 128 --tt "Foo Song Title" --ta "FooBar Artist" --tl "FooBar Album" \
---ty "2014" --tc "Ripped and encoded by Foo" --tg "Genre" audio01.wav audio01.mp3
+# pkg install moc
....
-The specified 128 kbits is a standard `MP3` bitrate while the 160 and 192 bitrates provide higher quality.
-The higher the bitrate, the larger the size of the resulting `MP3`.
-The `-h` turns on the "higher quality but a little slower" mode.
-The options beginning with `--t` indicate `ID3` tags, which usually contain song information, to be embedded within the `MP3` file.
-Additional encoding options can be found in the lame manual page.
-
-In order to burn an audio `CD` from ``MP3``s, they must first be converted to a non-compressed file format.
-XMMS can be used to convert to the `WAV` format, while mpg123 can be used to convert to the raw Pulse-Code Modulation (`PCM`) audio data format.
+[[video-ports]]
+== Video players
-To convert [.filename]#audio01.mp3# using mpg123, specify the name of the `PCM` file:
+This section introduces some of the software available from the FreeBSD Ports Collection which can be used for video playback.
-[source,shell]
-....
-# mpg123 -s audio01.mp3 > audio01.pcm
-....
+.Video players packages
+[options="header", cols="1,1,1,1"]
+|===
+| Name | License | Package | Toolkit
-To use XMMS to convert a `MP3` to `WAV` format, use these steps:
+| MPlayer
+| GPL 2.0
+| package:multimedia/mplayer[]
+| CLI
-[.procedure]
-.Procedure: Converting to `WAV` Format in XMMS
-. Launch XMMS.
-. Right-click the window to bring up the XMMS menu.
-. Select `Preferences` under `Options`.
-. Change the Output Plugin to "Disk Writer Plugin".
-. Press `Configure`.
-. Enter or browse to a directory to write the uncompressed files to.
-. Load the `MP3` file into XMMS as usual, with volume at 100% and EQ settings turned off.
-. Press `Play`. The XMMS will appear as if it is playing the `MP3`, but no music will be heard. It is actually playing the `MP3` to a file.
-. When finished, be sure to set the default Output Plugin back to what it was before in order to listen to ``MP3``s again.
+| SMPlayer
+| GPL 2.0
+| package:multimedia/smplayer[]
+| Qt
-Both the `WAV` and `PCM` formats can be used with cdrecord.
-When using `WAV` files, there will be a small tick sound at the beginning of each track.
-This sound is the header of the `WAV` file.
-The package:audio/sox[] port or package can be used to remove the header:
+| VLC media player
+| GPL 2.0
+| package:multimedia/vlc[]
+| Qt
-[source,shell]
-....
-% sox -t wav -r 44100 -s -w -c 2 track.wav track.raw
-....
+| Kodi (XBMC)
+| GPL 2.0
+| package:multimedia/kodi[]
+| X11
-Refer to crossref:disks[creating-cds,“Creating and Using CD Media”] for more information on using a `CD` burner in FreeBSD.
+|===
-[[video-playback]]
-== Video Playback
+[[mplayer]]
+=== MPlayer
-Before configuring video playback, determine the model and chipset of the video card.
-While Xorg supports a wide variety of video cards, not all provide good playback performance.
-To obtain a list of extensions supported by the Xorg server using the card, run `xdpyinfo` while Xorg is running.
+MPlayer is a multimedia player and encoder suite which runs on many platforms.
+It plays a terrific number of different file formats and codecs including popular DivX, XviD, H.264 streams as well as DVD and SVCDs along with many popular audio codecs.
-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]#/dev/dvd# by default, or have this device name hardcoded in them, it might be useful to make a symbolic link to the proper device:
+To install MPlayer, execute:
[source,shell]
....
-# ln -sf /dev/cd0 /dev/dvd
+# pkg install mplayer
....
-Due to the nature of man:devfs[5], manually created links will not persist after a system reboot.
-In order to recreate the symbolic link automatically when the system boots, add the following line to [.filename]#/etc/devfs.conf#:
+MPlayer is a video player that works on the command line.
+For examples of how MPlayer works see man:mplayer[1].
-[.programlisting]
-....
-link cd0 dvd
-....
+[[smplayer]]
+=== SMPlayer
-`DVD` decryption invokes certain functions that require write permission to the `DVD` device.
+SMPlayer intends to be a complete front-end for MPlayer, from basic features like playing videos, DVDs, and VCDs to more advanced features like support for MPlayer filters and more.
-To enhance the shared memory Xorg interface, it is recommended to increase the values of these man:sysctl[8] variables:
+To install SMPlayer, execute:
-[.programlisting]
+[source,shell]
....
-kern.ipc.shmmax=67108864
-kern.ipc.shmall=32768
+# pkg install smplayer
....
-[[video-interface]]
-=== Determining Video Capabilities
-
-There are several possible ways to display video under Xorg and what works is largely hardware dependent.
-Each method described below will have varying quality across different hardware.
-
-Common video interfaces include:
-
-. Xorg: normal output using shared memory.
-. XVideo: an extension to the Xorg interface which allows video to be directly displayed in drawable objects through a special acceleration. This extension provides good quality playback even on low-end machines. The next section describes how to determine if this extension is running.
-. `SDL`: the Simple Directmedia Layer is a porting layer for many operating systems, allowing cross-platform applications to be developed which make efficient use of sound and graphics. `SDL` provides a low-level abstraction to the hardware which can sometimes be more efficient than the Xorg interface. On FreeBSD, `SDL` can be installed using the package:devel/sdl20[] package or port.
-. `DGA`: the Direct Graphics Access is an Xorg extension which allows a program to bypass the Xorg server and directly alter the framebuffer. As it relies on a low-level memory mapping, programs using it must be run as `root`. The `DGA` extension can be tested and benchmarked using man:dga[1]. When `dga` is running, it changes the colors of the display whenever a key is pressed. To quit, press kbd:[q].
-. SVGAlib: a low level console graphics layer.
+[[vlc]]
+=== VLC media player
-[[video-interface-xvideo]]
-==== XVideo
+VLC media player is a highly portable multimedia player for various audio and video formats (MPEG-1, MPEG-2, MPEG-4, DivX, mp3, ogg, and more) as well as DVD's, VCD's, and various streaming protocols.
+It can also be used as a server to stream in unicast or multicast in IPv4 or IPv6 on a high-bandwidth network.
+VLC also has the ability to transcode media on-the-fly for streaming or saving to disk.
-To check whether this extension is running, use `xvinfo`:
+To install VLC, execute:
[source,shell]
....
-% xvinfo
+# pkg install vlc
....
-XVideo is supported for the card if the result is similar to:
+[[kodi]]
+=== Kodi (XBMC)
-[source,shell]
-....
-X-Video Extension version 2.2
- screen #0
- Adaptor #0: "Savage Streams Engine"
- number of ports: 1
- port base: 43
- operations supported: PutImage
- supported visuals:
- depth 16, visualID 0x22
- depth 16, visualID 0x23
- number of attributes: 5
- "XV_COLORKEY" (range 0 to 16777215)
- client settable attribute
- client gettable attribute (current value is 2110)
- "XV_BRIGHTNESS" (range -128 to 127)
- client settable attribute
- client gettable attribute (current value is 0)
- "XV_CONTRAST" (range 0 to 255)
- client settable attribute
- client gettable attribute (current value is 128)
- "XV_SATURATION" (range 0 to 255)
- client settable attribute
- client gettable attribute (current value is 128)
- "XV_HUE" (range -180 to 180)
- client settable attribute
- client gettable attribute (current value is 0)
- maximum XvImage size: 1024 x 1024
- Number of image formats: 7
- id: 0x32595559 (YUY2)
- guid: 59555932-0000-0010-8000-00aa00389b71
- bits per pixel: 16
- number of planes: 1
- type: YUV (packed)
- id: 0x32315659 (YV12)
- guid: 59563132-0000-0010-8000-00aa00389b71
- bits per pixel: 12
- number of planes: 3
- type: YUV (planar)
- id: 0x30323449 (I420)
- guid: 49343230-0000-0010-8000-00aa00389b71
- bits per pixel: 12
- number of planes: 3
- type: YUV (planar)
- id: 0x36315652 (RV16)
- guid: 52563135-0000-0000-0000-000000000000
- bits per pixel: 16
- number of planes: 1
- type: RGB (packed)
- depth: 0
- red, green, blue masks: 0x1f, 0x3e0, 0x7c00
- id: 0x35315652 (RV15)
- guid: 52563136-0000-0000-0000-000000000000
- bits per pixel: 16
- number of planes: 1
- type: RGB (packed)
- depth: 0
- red, green, blue masks: 0x1f, 0x7e0, 0xf800
- id: 0x31313259 (Y211)
- guid: 59323131-0000-0010-8000-00aa00389b71
- bits per pixel: 6
- number of planes: 3
- type: YUV (packed)
- id: 0x0
- guid: 00000000-0000-0000-0000-000000000000
- bits per pixel: 0
- number of planes: 0
- type: RGB (packed)
- depth: 1
- red, green, blue masks: 0x0, 0x0, 0x0
-....
-
-The formats listed, such as YUV2 and YUV12, are not present with every implementation of XVideo and their absence may hinder some players.
-
-If the result instead looks like:
+Kodi (formerly known as XBMC) is a free and open source cross-platform media-player and entertainment hub.
+It allows users to play and view most videos, music, podcasts, and other digital media files from local and network storage media and the internet.
+
+To install Kodi, execute:
[source,shell]
....
-X-Video Extension version 2.2
-screen #0
-no adaptors present
+# pkg install kodi
....
-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.
+[[conferencing-meetings]]
+== Conferencing and Meetings
-[[video-ports]]
-=== Ports and Packages Dealing with Video
+A FreeBSD desktop environment can be used to join video conferences.
+This section will explain how to configure the webcam and which videoconferencing applications are supported on FreeBSD.
-This section introduces some of the software available from the FreeBSD Ports Collection which can be used for video playback.
+[[webcam-setup]]
+=== Setting Up the Webcam
-[[video-mplayer]]
-==== MPlayer and MEncoder
+To allow FreeBSD access to the webcam and perform its configuration it is necessary to install certain utilities:
-MPlayer is a command-line video player with an optional graphical interface which aims to provide speed and flexibility.
-Other graphical front-ends to MPlayer are available from the FreeBSD Ports Collection.
+* package:multimedia/webcamd[] is a daemon that enables the use of hundreds of different USB based webcam and DVB USB devices.
+* package:multimedia/pwcview[] is an application that can be used to view the video stream of the webcam.
-MPlayer can be installed using the package:multimedia/mplayer[] package or port.
-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.
-
-When compiling the port, the menu options should be reviewed to determine the type of support to compile into the port.
-If an option is not selected, MPlayer 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 kbd:[Enter] to continue the port compile and installation.
-
-By default, the package or port will build the `mplayer` command line utility and the `gmplayer` graphical utility.
-To encode videos, compile the package:multimedia/mencoder[] port.
-Due to licensing restrictions, a package is not available for MEncoder.
-
-The first time MPlayer is run, it will create [.filename]#~/.mplayer# in the user's home directory.
-This subdirectory contains default versions of the user-specific configuration files.
-
-This section describes only a few common uses.
-Refer to mplayer(1) for a complete description of its numerous options.
-
-To play the file [.filename]#testfile.avi#, specify the video interfaces with `-vo`, as seen in the following examples:
+To install the required utilities, execute:
[source,shell]
....
-% mplayer -vo xv testfile.avi
+# pkg install webcamd pwcview
....
-[source,shell]
-....
-% mplayer -vo sdl testfile.avi
-....
+Enable man:webcamd[8] service in `/etc/rc.conf` to start at system boot:
[source,shell]
....
-% mplayer -vo x11 testfile.avi
+# sysrc webcamd_enable="YES"
....
-[source,shell]
-....
-# mplayer -vo dga testfile.avi
-....
+The user must belong to the `webcamd` group.
+To add the user to `webcamd` group execute the following command:
[source,shell]
....
-# mplayer -vo 'sdl:dga' testfile.avi
+# pw groupmod webcamd -m username
....
-It is worth trying all of these options, as their relative performance depends on many factors and will vary significantly with hardware.
-
-To play a `DVD`, replace [.filename]#testfile.avi# with `dvd://_N_ -dvd-device _DEVICE_`, where _N_ is the title number to play and _DEVICE_ is the device node for the `DVD`.
-For example, to play title 3 from [.filename]#/dev/dvd#:
+Since package:multimedia/webcamd[] needs the man:cuse[3] module this module must be loaded executing the following command:
[source,shell]
....
-# mplayer -vo xv dvd://3 -dvd-device /dev/dvd
-....
-
-[NOTE]
-====
-The default `DVD` device can be defined during the build of the MPlayer port by including the `WITH_DVD_DEVICE=/path/to/desired/device` option.
-By default, the device is [.filename]#/dev/cd0#. More details can be found in the port's [.filename]#Makefile.options#.
-====
-
-To stop, pause, advance, and so on, use a keybinding.
-To see the list of keybindings, run `mplayer -h` or read mplayer(1).
-
-Additional playback options include `-fs -zoom`, which engages fullscreen mode, and `-framedrop`, which helps performance.
-
-Each user can add commonly used options to their [.filename]#~/.mplayer/config# like so:
-
-[.programlisting]
-....
-vo=xv
-fs=yes
-zoom=yes
+# kldload cuse
....
-`mplayer` can be used to rip a `DVD` title to a [.filename]#.vob#.
-To dump the second title from a `DVD`:
+To load man:cuse[3] at system boot execute the command:
[source,shell]
....
-# mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd
+# kld_list += "cuse"
....
-The output file, [.filename]#out.vob#, will be in `MPEG` format.
-
-Anyone wishing to obtain a high level of expertise with UNIX(R) video should consult http://www.mplayerhq.hu/DOCS/[mplayerhq.hu/DOCS] as it is technically informative.
-This documentation should be considered as required reading before submitting any bug reports.
-
-Before using `mencoder`, it is a good idea to become familiar with the options described at http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html[mplayerhq.hu/DOCS/HTML/en/mencoder.html].
-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 `mplayer`.
-
-Here is an example of a simple copy:
+Once the utilities have been installed the list of available webcams can be shown with man:webcamd[8]:
[source,shell]
....
-% mencoder input.avi -oac copy -ovc copy -o output.avi
+# webcamd -l
....
-To rip to a file, use `-dumpfile` with `mplayer`.
+The output should be similar to the following:
-To convert [.filename]#input.avi# to the MPEG4 codec with MPEG3 audio encoding, first install the package:audio/lame[] port.
-Due to licensing restrictions, a package is not available.
-Once installed, type:
-
-[source,shell]
+[.programlisting]
....
-% mencoder input.avi -oac mp3lame -lameopts br=192 \
- -ovc lavc -lavcopts vcodec=mpeg4:vhq -o output.avi
+webcamd [-d ugen0.2] -N SunplusIT-Inc-HP-TrueVision-HD-Camera -S unknown -M 0 <.>
+webcamd [-d ugen1.3] -N Realtek-802-11n-WLAN-Adapter -S 00e04c000001 -M 0
....
+<.> Available webcam
-This will produce output playable by applications such as `mplayer` and `xine`.
-
-[.filename]#input.avi# can be replaced with `dvd://1 -dvd-device /dev/dvd` and run as `root` to re-encode a `DVD` title directly.
-Since it may take a few tries to get the desired result, it is recommended to instead dump the title to a file and to work on the file.
-
-[[video-xine]]
-==== The xine Video Player
-
-xine 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 package:multimedia/xine[] package or port.
-
-In practice, xine requires either a fast CPU with a fast video card, or support for the XVideo extension.
-The xine video player performs best on XVideo interfaces.
-
-By default, the xine player starts a graphical user interface.
-The menus can then be used to open a specific file.
-
-Alternatively, xine may be invoked from the command line by specifying the name of the file to play:
+Configure the available webcam executing the following command:
[source,shell]
....
-% xine -g -p mymovie.avi
+# sysrc webcamd_0_flags="-d ugen0.2" <.>
....
-Refer to http://www.xine-project.org/faq[xine-project.org/faq] for more information and troubleshooting tips.
-
-[[video-ports-transcode]]
-==== The Transcode Utilities
-
-Transcode provides a suite of tools for re-encoding video and audio files.
-Transcode can be used to merge video files or repair broken files using command line tools with stdin/stdout stream interfaces.
-
-In FreeBSD, Transcode can be installed using the package:multimedia/transcode[] 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, Transcode will not be able to encode that format.
-Use the arrow keys and spacebar to select the required formats.
-When finished, press kbd:[Enter] to continue the port compile and installation.
+[NOTE]
+====
+Note here that if this is a plug-and-play USB webcam, changing the USB port to which it is connected, will change the output from `webcamd -l`, hence the entry in rc.conf might need updating.
+For laptops (that use USB integrated webcams) this won't be an issue though.
+====
-This example demonstrates how to convert a DivX file into a PAL MPEG-1 file (PAL VCD):
+The man:webcamd[8] service must be started executing the following command:
[source,shell]
....
-% transcode -i input.avi -V --export_prof vcd-pal -o output_vcd
-% mplex -f 1 -o output_vcd.mpg output_vcd.m1v output_vcd.mpa
+# service webcamd start
....
-The resulting `MPEG` file, [.filename]#output_vcd.mpg#, is ready to be played with MPlayer.
-The file can be burned on a `CD` media to create a video `CD` using a utility such as package:multimedia/vcdimager[] or package:sysutils/cdrdao[].
-
-In addition to the manual page for `transcode`, refer to http://www.transcoding.org/cgi-bin/transcode[transcoding.org/cgi-bin/transcode] for further information and examples.
-
-[[tvcard]]
-== TV Cards
-
-TV cards 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.
-
-FreeBSD provides support for PCI-based TV cards using a Brooktree Bt848/849/878/879 video capture chip with the man:bktr[4] driver.
-This driver supports most Pinnacle PCTV video cards.
-Before purchasing a TV card, consult man:bktr[4] for a list of supported tuners.
-
-=== Loading the Driver
-
-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#:
-
-[.programlisting]
-....
-bktr_load="YES"
-....
-
-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:
+The output should be similar to the following:
[.programlisting]
....
-device bktr
-device iicbus
-device iicbb
-device smbus
+Starting webcamd.
+webcamd 1616 - - Attached to ugen0.2[0]
....
-These additional devices are necessary as the card components are interconnected via an I2C bus.
-Then, build and install a new kernel.
+To start webcamd automatically at system startup, execute the following command:
-To test that the tuner is correctly detected, reboot the system.
-The TV card should appear in the boot messages, as seen in this example:
-
-[.programlisting]
-....
-bktr0: <BrookTree 848A> mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0
-iicbb0: <I2C bit-banging driver> on bti2c0
-iicbus0: <Philips I2C bus> on iicbb0 master-only
-iicbus1: <Philips I2C bus> on iicbb0 master-only
-smbus0: <System Management Bus> on bti2c0
-bktr0: Pinnacle/Miro TV, Philips SECAM tuner.
-....
-
-The messages will differ according to the hardware.
-If necessary, it is possible to override some of the detected parameters using man:sysctl[8] or custom kernel configuration options.
-For example, to force the tuner to a Philips SECAM tuner, add the following line to a custom kernel configuration file:
-
-[.programlisting]
+[source,shell]
....
-options OVERRIDE_TUNER=6
+# sysrc webcamd_enable="YES"
....
-or, use man:sysctl[8]:
+package:multimedia/pwcview[] can be used to check the proper functioning of the webcam.
+The following command can be used to execute package:multimedia/pwcview[]:
[source,shell]
....
-# sysctl hw.bt848.tuner=6
+% pwcview -f 30 -s vga
....
-Refer to man:bktr[4] for a description of the available man:sysctl[8] parameters and kernel options.
-
-=== Useful Applications
-
-To use the TV card, install one of the following applications:
+Then package:multimedia/pwcview[] will display the webcam:
-* package:multimedia/fxtv[] provides TV-in-a-window and image/audio/video capture capabilities.
-* package:multimedia/xawtv[] is another TV application with similar features.
-* package:audio/xmradio[] provides an application for using the FM radio tuner of a TV card.
+image::pwcview.png[pwcview showing Absolute FreeBSD 3rd edition as an example]
-More applications are available in the FreeBSD Ports Collection.
+[[meetings-software-status]]
+=== Meetings software status
-=== Troubleshooting
+FreeBSD currently supports the main tools used to carry out videoconferences.
-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 or to ask questions about supported TV cards, refer to the {freebsd-multimedia} mailing list.
-
-[[mythtv]]
-== MythTV
-
-MythTV is a popular, open source Personal Video Recorder (`PVR`) application.
-This section demonstrates how to install and setup MythTV on FreeBSD.
-Refer to http://www.mythtv.org/wiki/[mythtv.org/wiki] for more information on how to use MythTV.
-
-MythTV requires a frontend and a backend.
-These components can either be installed on the same system or on different machines.
-
-The frontend can be installed on FreeBSD using the package:multimedia/mythtv-frontend[] package or port.
-Xorg must also be installed and configured as described in crossref:x11[x11,The X Window System].
-Ideally, this system has a video card that supports X-Video Motion Compensation (`XvMC`) and, optionally, a Linux Infrared Remote Control (`LIRC`)-compatible remote.
-
-To install both the backend and the frontend on FreeBSD, use the package:multimedia/mythtv[] package or port.
-A MySQL(TM) database server is also required and should automatically be installed as a dependency.
-Optionally, this system should have a tuner card and sufficient storage to hold recorded data.
-
-=== Hardware
-
-MythTV uses Video for Linux (`V4L`) to access video input devices such as encoders and tuners.
-In FreeBSD, MythTV works best with `USB` DVB-S/C/T cards as they are well supported by the package:multimedia/webcamd[] package or port which provides a `V4L` userland application.
-Any Digital Video Broadcasting (`DVB`) card supported by webcamd should work with MythTV.
-A list of known working cards can be found at https://wiki.freebsd.org/WebcamCompat[wiki.freebsd.org/WebcamCompat].
-Drivers are also available for Hauppauge cards in the package:multimedia/pvr250[] and package:multimedia/pvrxxx[] ports, but they provide a non-standard driver interface that does not work with versions of MythTV greater than 0.23.
-Due to licensing restrictions, no packages are available and these two ports must be compiled.
-
-The https://wiki.freebsd.org/HTPC[wiki.freebsd.org/HTPC] page contains a list of all available `DVB` drivers.
-
-=== Setting up the MythTV Backend
-
-To install MythTV using binary packages:
-
-[source,shell]
-....
-# pkg install mythtv
-....
-
-Alternatively, to install from the Ports Collection:
-
-[source,shell]
-....
-# cd /usr/ports/multimedia/mythtv
-# make install
-....
+.Meeting software
+[options="header", cols="1,1,1,1"]
+|===
+| Name | Firefox status | Chromium status | Website
-Once installed, set up the MythTV database:
+| Microsoft Teams
+| Does not work
+| Works
+| link:https://teams.live.com[]
-[source,shell]
-....
-# mysql -uroot -p < /usr/local/share/mythtv/database/mc.sql
-....
+| Google Meet
+| Does not work
+| Works
+| link:https://meet.google.com/[]
-Then, configure the backend:
+| Zoom
+| Works
+| Works
+| link:https://zoom.us[]
-[source,shell]
-....
-# mythtv-setup
-....
+| Jitsi
+| Does not work
+| Works
+| link:https://meet.jit.si/[]
-Finally, start the backend:
+| BigBlueButton
+| Does not work
+| Works
+| link:https://bigbluebutton.org/[]
-[source,shell]
-....
-# sysrc mythbackend_enable=yes
-# service mythbackend start
-....
+|===
[[scanners]]
== Image Scanners
-In FreeBSD, access to image scanners is provided by SANE (Scanner Access Now Easy), which is available in the FreeBSD Ports Collection.
-SANE will also use some FreeBSD device drivers to provide access to the scanner hardware.
-
-FreeBSD supports both `SCSI` and `USB` scanners.
-Depending upon the scanner interface, different device drivers are required.
-Be sure the scanner is supported by SANE prior to performing any configuration.
-Refer to http://www.sane-project.org/sane-supported-devices.html[http://www.sane-project.org/sane-supported-devices.html] for more information about supported scanners.
-
-This chapter describes how to determine if the scanner has been detected by FreeBSD.
-It then provides an overview of how to configure and use SANE on a FreeBSD system.
+In FreeBSD, access to image scanners is provided by link:http://www.sane-project.org[SANE (Scanner Access Now Easy)], which is available in the FreeBSD Ports Collection.
[[scanners-kernel-usb]]
=== Checking the Scanner
-The [.filename]#GENERIC# kernel includes the device drivers needed to support `USB` scanners.
-Users with a custom kernel should ensure that the following lines are present in the custom kernel configuration file:
-
-[.programlisting]
-....
-device usb
-device uhci
-device ohci
-device ehci
-device xhci
-....
+Before making any configuration it is important to check the scanner is supported by SANE.
-To determine if the `USB` scanner is detected, plug it in and use `dmesg` to determine whether the scanner appears in the system message buffer.
-If it does, it should display a message similar to this:
+With the scanner connected, run the following command to get all connected USB devices:
[source,shell]
....
-ugen0.2: <EPSON> at usbus0
+# usbconfig list
....
-In this example, an EPSON Perfection(R) 1650 `USB` scanner was detected on [.filename]#/dev/ugen0.2#.
-
-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# kernel supports the most common `SCSI` controllers.
-Refer to [.filename]#/usr/src/sys/conf/NOTES# 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 a custom kernel configuration file:
+The output should be similar to the following:
[.programlisting]
....
-device scbus
-device pass
+ugen4.2: <LITE-ON Technology USB NetVista Full Width Keyboard.> at usbus4, cfg=0 md=HOST spd=LOW (1.5Mbps) pwr=ON (70mA)
+ugen4.3: <Logitech USB Optical Mouse> at usbus4, cfg=0 md=HOST spd=LOW (1.5Mbps) pwr=ON (100mA)
+ugen3.2: <HP Deskjet 1050 J410 series> at usbus3, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA)
....
-Verify that the device is displayed in the system message buffer:
+Run the following command to obtain the `idVendor` and the `idProduct`:
[source,shell]
....
-pass2 at aic0 bus 0 target 2 lun 0
-pass2: <AGFA SNAPSCAN 600 1.10> Fixed Scanner SCSI-2 device
-pass2: 3.300MB/s transfers
+# usbconfig -d 3.2 dump_device_desc
....
-If the scanner was not powered-on at system boot, it is still possible to manually force detection by performing a `SCSI` bus scan with `camcontrol`:
-
-[source,shell]
-....
-# camcontrol rescan all
-Re-scan of bus 0 was successful
-Re-scan of bus 1 was successful
-Re-scan of bus 2 was successful
-Re-scan of bus 3 was successful
-....
+[NOTE]
+====
+Note here that the scanner is a plug-and-play device, changing the USB port to which it is connected, will change the output from `usbconfig list`.
+====
-The scanner should now appear in the `SCSI` devices list:
+The output should be similar to the following:
-[source,shell]
+[.programlisting]
....
-# camcontrol devlist
-<IBM DDRS-34560 S97B> at scbus0 target 5 lun 0 (pass0,da0)
-<IBM DDRS-34560 S97B> at scbus0 target 6 lun 0 (pass1,da1)
-<AGFA SNAPSCAN 600 1.10> at scbus1 target 2 lun 0 (pass3)
-<PHILIPS CDD3610 CD-R/RW 1.00> at scbus2 target 0 lun 0 (pass2,cd0)
+ugen3.2: <HP Deskjet 1050 J410 series> at usbus3, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA)
+
+bLength = 0x0012
+bDescriptorType = 0x0001
+bcdUSB = 0x0200
+bDeviceClass = 0x0000 <Probed by interface class>
+bDeviceSubClass = 0x0000
+bDeviceProtocol = 0x0000
+bMaxPacketSize0 = 0x0040
+idVendor = 0x03f0
+idProduct = 0x8911
+bcdDevice = 0x0100
+iManufacturer = 0x0001 <HP>
+iProduct = 0x0002 <Deskjet 1050 J410 series>
+bNumConfigurations = 0x0001
....
-Refer to man:scsi[4] and man:camcontrol[8] for more details about `SCSI` devices on FreeBSD.
+Once the `idVendor` and the `idProduct` have been obtained, it is necessary to check in the link:http://www.sane-project.org/lists/sane-mfgs-cvs.html[list of supported devices of SANE] if the scanner is supported by filtering by the idProduct.
+[[_sane_configuration]]
=== SANE Configuration
-The SANE system provides the access to the scanner via backends (package:graphics/sane-backends[]).
-Refer to http://www.sane-project.org/sane-supported-devices.html[http://www.sane-project.org/sane-supported-devices.html] to determine which backend supports the scanner.
-A graphical scanning interface is provided by third party applications like Kooka (package:graphics/kooka[]) or XSane (package:graphics/xsane[]).
-SANE's backends are enough to test the scanner.
-
-To install the backends from binary package:
+SANE provides the access to the scanner via backends.
+To be able to scan with FreeBSD the package:graphics/sane-backends[] package must be installed by running the following command:
[source,shell]
....
# pkg install sane-backends
....
-Alternatively, to install from the Ports Collection
-
-[source,shell]
-....
-# cd /usr/ports/graphics/sane-backends
-# make install clean
-....
-
-After installing the package:graphics/sane-backends[] port or package, use `sane-find-scanner` to check the scanner detection by the SANE system:
-
-[source,shell]
-....
-# sane-find-scanner -q
-found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3
-....
-
-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.
-
-[NOTE]
+[TIP]
====
-Some `USB` scanners require firmware to be loaded.
-Refer to sane-find-scanner(1) and sane(7) for details.
+Some USB scanners require firmware to be loaded.
+Like the HP scanner used in the example above, which needs the package package:print/hplip[] installed.
====
-Next, check if the scanner will be identified by a scanning frontend.
-The SANE backends include `scanimage` which can be used to list the devices and perform an image acquisition.
-Use `-L` to list the scanner devices.
-The first example is for a `SCSI` scanner and the second is for a `USB` scanner:
+After installing the necessary packages man:devd[8] must be configured to allow FreeBSD access to the scanner.
-[source,shell]
-....
-# scanimage -L
-device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner
-
-# scanimage -L
-device 'epson2:libusb:000:002' is a Epson GT-8200 flatbed scanner
-....
-
-In this second example, `epson2` is the backend name and `libusb:000:002` means [.filename]#/dev/ugen0.2# is the device node used by the scanner.
-
-If `scanimage` is unable to identify the scanner, this message will appear:
-
-[source,shell]
-....
-# scanimage -L
-No scanners were identified. If you were expecting something different,
-check that the scanner is plugged in, turned on and detected by the
-sane-find-scanner tool (if appropriate). Please read the documentation
-which came with this software (README, FAQ, manpages).
-....
-
-If this happens, edit the backend configuration file in [.filename]#/usr/local/etc/sane.d/# and define the scanner device used.
-For example, if the undetected scanner model is an EPSON Perfection(R) 1650 and it uses the `epson2` backend, edit [.filename]#/usr/local/etc/sane.d/epson2.conf#.
-When editing, add a line specifying the interface and the device node used.
-In this case, add the following line:
+Add the `saned.conf` file to [.filename]#/usr/local/etc/devd/saned.conf# with the following content:
[.programlisting]
....
-usb /dev/ugen0.2
+notify 100 {
+ match "system" "USB";
+ match "subsystem" "INTERFACE";
+ match "type" "ATTACH";
+ match "cdev" "ugen[0-9].[0-9]";
+ match "vendor" "0x03f0"; <.>
+ match "product" "0x8911"; <.>
+ action "chown -L cups:saned /dev/\$cdev && chmod -L 660 /dev/\$cdev";
+};
....
-Save the edits and verify that the scanner is identified with the right backend name and the device node:
+<.> `vendor`: Is the idVendor obtained previously by running the `usbconfig -d 3.2 dump_device_desc` command.
+<.> `product`: Is the idProduct obtained previously by running the `usbconfig -d 3.2 dump_device_desc` command.
+
+After that man:devd[8] must be restarted by running the following command:
[source,shell]
....
-# scanimage -L
-device 'epson2:libusb:000:002' is a Epson GT-8200 flatbed scanner
+# service devd restart
....
-Once `scanimage -L` sees the scanner, the configuration is complete and the scanner is now ready to use.
-
-While `scanimage` 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.
-Applications like Kooka or XSane are popular scanning frontends.
-They offer advanced features such as various scanning modes, color correction, and batch scans.
-XSane is also usable as a GIMP plugin.
-
-=== Scanner Permissions
-
-In order to have access to the scanner, a user needs read and write permissions to the device node used by the scanner.
-In the previous example, the `USB` scanner uses the device node [.filename]#/dev/ugen0.2# which is really a symlink to the real device node [.filename]#/dev/usb/0.2.0#.
-The symlink and the device node are owned, respectively, by the `wheel` and `operator` groups.
-While adding the user to these groups will allow access to the scanner, it is considered insecure to add a user to `wheel`.
-A better solution is to create a group and make the scanner device accessible to members of this group.
+The SANE backends include man:scanimage[1] which can be used to list the devices and perform an image acquisition.
-This example creates a group called `_usb_`:
+Execute man:scanimage[1] with `-L` argument to list the scanner devices:
[source,shell]
....
-# pw groupadd usb
+# scanimage -L
....
-Then, make the [.filename]#/dev/ugen0.2# symlink and the [.filename]#/dev/usb/0.2.0# device node accessible to the `usb` group with write permissions of `0660` or `0664` by adding the following lines to [.filename]#/etc/devfs.rules#:
+The output should be similar to the following:
[.programlisting]
....
-[system=5]
-add path ugen0.2 mode 0660 group usb
-add path usb/0.2.0 mode 0666 group usb
+device `hpaio:/usb/Deskjet_1050_J410_series?serial=XXXXXXXXXXXXXX' is a Hewlett-Packard Deskjet_1050_J410_series all-in-one
....
-[NOTE]
-====
-It happens the device node changes with the addition or removal of devices, so one may want to give access to all USB devices using this ruleset instead:
+If man:scanimage[1] is not able to identify the scanner, this message will appear:
[.programlisting]
....
-[system=5]
-add path 'ugen*' mode 0660 group usb
-add path 'usb/*' mode 0666 group usb
+No scanners were identified. If you were expecting something different,
+check that the scanner is plugged in, turned on and detected by the
+sane-find-scanner tool (if appropriate). Please read the documentation
+which came with this software (README, FAQ, manpages).
....
-====
+Once man:scanimage[1] sees the scanner, the configuration is complete and the scanner is now ready to use.
-Refer to man:devfs.rules[5] for more information about this file.
+To activate the service and have it run at boot execute the following command:
-Next, enable the ruleset in /etc/rc.conf:
-
-[.programlisting]
+[source,shell]
....
-devfs_system_ruleset="system"
+# sysrc saned_enable="YES"
....
-And, restart the man:devfs[8] system:
+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.
-[source,shell]
-....
-# service devfs restart
-....
+.Graphical scanner programs
+[options="header", cols="1,1,1"]
+|===
+| Name | License | Package
-Finally, add the users to `_usb_` in order to allow access to the scanner:
+| skanlite
+| GPL 2.0
+| graphics/skanlite
-[source,shell]
-....
-# pw groupmod usb -m joe
-....
+| GNOME Simple Scan
+| GPL 3.0
+| graphics/simple-scan
-For more details refer to man:pw[8].
+| XSANE
+| GPL 2.0
+| graphics/xsane
+
+|===
diff --git a/documentation/static/images/books/handbook/multimedia/pwcview.png b/documentation/static/images/books/handbook/multimedia/pwcview.png
new file mode 100644
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000
GIT binary patch
literal 0
Hc$@<O00001
literal 0
Hc$@<O00001

File Metadata

Mime Type
text/plain
Expires
Wed, Nov 20, 4:20 AM (21 h, 34 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
14730129
Default Alt Text
D38798.diff (61 KB)

Event Timeline