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: at nid 26,22 and 24 on hdaa0 +pcm1: 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: (play/rec) default +pcm1: (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: at nid 5 on hdaa0 -pcm1: at nid 6 on hdaa0 -pcm2: 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: (play) -pcm1: (play) -pcm2: (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: at cad 0 nid 1 on hdac0 +pcm1: at cad 1 nid 1 on hdac0 +pcm2: at cad 2 nid 1 on hdac0 +pcm3: at cad 3 nid 1 on hdac0 +hdac1: HDA Codec #2: Realtek ALC889 +pcm4: at cad 2 nid 1 on hdac1 +pcm5: at cad 2 nid 1 on hdac1 +pcm6: at cad 2 nid 1 on hdac1 +pcm7: 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: at nid 23 and 26 on hdaa0 +pcm1: 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 -<> 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: at cad 0 nid 1 on hdac0 -pcm1: at cad 1 nid 1 on hdac0 -pcm2: at cad 2 nid 1 on hdac0 -pcm3: at cad 3 nid 1 on hdac0 -hdac1: HDA Codec #2: Realtek ALC889 -pcm4: at cad 2 nid 1 on hdac1 -pcm5: at cad 2 nid 1 on hdac1 -pcm6: at cad 2 nid 1 on hdac1 -pcm7: 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: mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0 -iicbb0: on bti2c0 -iicbus0: on iicbb0 master-only -iicbus1: on iicbb0 master-only -smbus0: 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: 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: at usbus4, cfg=0 md=HOST spd=LOW (1.5Mbps) pwr=ON (70mA) +ugen4.3: at usbus4, cfg=0 md=HOST spd=LOW (1.5Mbps) pwr=ON (100mA) +ugen3.2: 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: 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 - at scbus0 target 5 lun 0 (pass0,da0) - at scbus0 target 6 lun 0 (pass1,da1) - at scbus1 target 2 lun 0 (pass3) - at scbus2 target 0 lun 0 (pass2,cd0) +ugen3.2: at usbus3, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA) + +bLength = 0x0012 +bDescriptorType = 0x0001 +bcdUSB = 0x0200 +bDeviceClass = 0x0000 +bDeviceSubClass = 0x0000 +bDeviceProtocol = 0x0000 +bMaxPacketSize0 = 0x0040 +idVendor = 0x03f0 +idProduct = 0x8911 +bcdDevice = 0x0100 +iManufacturer = 0x0001 +iProduct = 0x0002 +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$@