diff --git a/documentation/content/en/books/handbook/multimedia/_index.adoc b/documentation/content/en/books/handbook/multimedia/_index.adoc index fb6f696f35..f2fc5b3697 100644 --- a/documentation/content/en/books/handbook/multimedia/_index.adoc +++ b/documentation/content/en/books/handbook/multimedia/_index.adoc @@ -1,839 +1,839 @@ --- title: Chapter 9. Multimedia part: Part II. Common Tasks prev: books/handbook/desktop next: books/handbook/kernelconfig 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: 12 params: path: "/books/handbook/multimedia/" --- [[multimedia]] = Multimedia :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumoffset: 9 :partnums: :source-highlighter: rouge :experimental: :images-path: books/handbook/multimedia/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[multimedia-synopsis]] == Synopsis 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. FreeBSD provides a robust platform for multimedia work, suitable for both multimedia enthusiasts and professional content creators. 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 By default, FreeBSD will automatically detect the sound card used by the system. FreeBSD supports a wide variety of sound cards. The list of supported sound cards can be consulted in man:sound[4]. [NOTE] ==== It is only necessary to load the sound card module if FreeBSD has not detected it correctly. ==== Where it is not known which sound card the system has, or which module to use, the `snd_driver` metadriver can be loaded by executing the following command: [source,shell] .... # kldload snd_driver .... Alternatively, to load the driver as a module at boot time, place the following line in [.filename]#/boot/loader.conf#: [.programlisting] .... snd_driver_load="YES" .... [[sound-testing]] === Testing Sound To confirm the sound card is detected the following command can be executed: [source,shell] .... % dmesg | grep pcm .... The output should be similar to the following: [.programlisting] .... pcm0: at nid 26,22 and 24 on hdaa0 pcm1: at nid 29 on hdaa0 .... The status of the sound card may also be checked using this command: [source,shell] .... # cat /dev/sndstat .... The output should be similar to the following: [.programlisting] .... Installed devices: pcm0: (play/rec) default pcm1: (rec) .... 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. man:beep[1] can be used to produce some noise, confirming that the sound card is working: [source,shell] .... % beep .... [[sound-mixer]] === Mixer FreeBSD has different utilities to set and display sound card mixer values built on the FreeBSD Sound System: .Supported mixer packages [options="header", cols="1,1,1,1"] |=== | Name | License | Package | Toolkit | man:mixer[8] | BSD-2 | Included in base system | CLI | dsbmixer | BSD-2 | package:audio/dsbmixer[] | Qt | KDE Plasma audio widget | GPL 2.0 | package:audio/plasma6-plasma-pa[] | Qt | mixertui | BSD-2 | package:audio/mixertui[] | TUI |=== [[graphics-card-sound]] === Graphics Card Sound Graphics cards often come with their own integrated sound devices, and it may be unclear which is being used as the default device. To confirm, run dmesg and look for the pcm entries to identify how the system is enumerating the outputs. Execute the following command: [source,shell] .... % dmesg | grep pcm .... The output looks something like this: [.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 .... The graphics card (NVIDIA(R)) has been enumerated before the sound card (Realtek(R)), with the sound card appearing as `pcm4`. The system can be configured to use the sound card as the default device by executing the following command: [source,shell] .... # sysctl hw.snd.default_unit=4 .... To make this change permanent add the next line to [.filename]#/etc/sysctl.conf#: [.programlisting] .... hw.snd.default_unit=4 .... [[automatically-switching-headphones]] === Automatically Switching to Headphones Some systems may struggle with switching between audio outputs, but fortunately FreeBSD allows automatic switchover to be configured in [.filename]#device.hints#. Identify how the system is enumerating the audio outputs by executing the following command: [source,shell] .... % dmesg | grep pcm .... The output looks something like this: [.programlisting] .... pcm0: at nid 23 and 26 on hdaa0 pcm1: at nid 22 on hdaa0 .... Add the following lines to [.filename]#/boot/device.hints#: [.programlisting] .... -hint.hdac.0.cad0.nid22.config="as=1 seq=15 device=Headphones" +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] ==== Keep in mind that these values are for the example indicated above. They may vary depending on the system. ==== [[resampling-quality]] === Resampling Quality The process of changing the sample rate of an audio stream is called resampling. -This usually happens automatically in situations like recording audio with an DI or simply when playing back audio files with very low resolution. +This usually happens automatically in situations like recording audio with a DI (Digital Interface) or simply when playing back audio files with very low resolution. -Example: DI (Digital Interface) uses 192000 kHz, application only accepts 48000 kHz (or the other way around). +Example: DI uses 192000 kHz, application only accepts 48000 kHz (or the other way around). If possible, this should be adjusted outside the sound device driver, but for cases where this is not possible (Or the hardware is bad at resampling), you have influence over the quality that is used for resampling. Should you be unsure if you need this, for normal music listening, doing meetings and so on the default value is totally fine and most applications use 48000 kHz anyway, so resampling rarely happens. When making music, recording sounds otherwise where quality matters or you are an audiophile, you can increase the resampling quality. For the highest possible resample quality, execute the following command: [source,shell] .... # sysctl hw.snd.feeder_rate_quality=4<.> # sysctl hw.snd.feeder_rate_round=0<.> .... <.> 100dB stopband, 164 taps and 97% bandwidth <.> Large prime divisions for high accuracy To keep these values after reboots, they can be added to the `/etc/sysctl.conf`. It is important to keep in mind that adjusting the resample quality has influence on CPU usage and delay. More details about resampling can be read in man:sound[4] [[troubleshooting-sound]] === Troubleshooting Sound Some common error messages and their solutions: [[multimedia-sound-common-error-messages]] .Common Error Messages [cols="1,1", frame="none", options="header"] |=== | Error | Solution |`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. |=== 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. Alternatively, package:audio/pulseaudio[] settings can be changed on the fly. man:pacmd[1] opens a command line connection to the package:audio/pulseaudio[] daemon: [source,shell] .... # pacmd Welcome to PulseAudio 14.2! Use "help" for usage information. >>> .... The following command changes the default sink to card number 4 as in the previous example: [.programlisting] .... set-default-sink 4 .... [WARNING] ==== Do not use the `exit` command to exit the command line interface. That will kill the package:audio/pulseaudio[] daemon. Use kbd:[Ctrl+D] instead. ==== [[audio-ports]] == Audio players This section introduces some of the software available from the FreeBSD Ports Collection which can be used for audio playback. .Audio players packages [options="header", cols="1,1,1,1"] |=== | Name | License | Package | Toolkit | Elisa | LGPL 3.0 | package:audio/elisa[] | Qt | GNOME Music | GPL 2.0 | package:audio/gnome-music[] | GTK+ | Audacious | BSD-2 | package:multimedia/audacious[] | Qt | cmus — C* Music Player | GPL 2.0 | package:audio/cmus[] | TUI |=== [[elisa]] === Elisa Elisa is a music player developed by the KDE community that strives to be simple and nice to use. To install Elisa, execute: [source,shell] .... # pkg install elisa .... [[gnome-music]] === GNOME Music GNOME Music is the new GNOME music playing application. It aims to combine an elegant and immersive browsing experience with simple and straightforward controls. To install GNOME Music, execute: [source,shell] .... # pkg install gnome-music .... [[audacious]] === Audacious Audacious is an open source audio player. As a descendant of XMMS, it provides music playback while maintaining efficient use of system resources. To install Audacious, execute: [source,shell] .... # pkg install audacious-qt6 audacious-plugins-qt6 .... [NOTE] ==== Audacious supports OSS natively, but must be configured in the settings on the Audio tab. ==== [[moc-music-on-console]] [[cmus]] === cmus — C* Music Player cmus is a small, fast and powerful console music player for Unix-like operating systems. Beside various input and output plugins, it has support for CUE sheets, uses Unicode, supports scrobbling (to e.g. last.fm or libre.fm), can run external programs on selected files like tag-editors, can be controlled via UNIX sockets and many more. To install cmus, execute: [source,shell] .... # pkg install cmus .... [[video-ports]] == Video players This section introduces some of the software available from the FreeBSD Ports Collection which can be used for video playback. .Video players packages [options="header", cols="1,1,1,1"] |=== | Name | License | Package | Toolkit | mpv | GPL 2.0 | package:multimedia/mpv[] | CLI | SMPlayer | GPL 2.0 | package:multimedia/smplayer[] | Qt | VLC media player | GPL 2.0 | package:multimedia/vlc[] | Qt -| Kodi (XBMC) +| Kodi (XBMC) | GPL 2.0 | package:multimedia/kodi[] | X11 |=== [[mplayer]] [[mpv]] === mpv mpv is a free (as in freedom) media player for the command line. It supports a wide variety of media file formats, audio and video codecs, and subtitle types. mpv can leverage most hardware decoding APIs on all platforms. Also targeted towards vidoephile, it has several high quality up-/downscaling algorithms which can also be, like all settings, controlled via profiles. Profiles can be selected via command-line switches or based on conditions like the folder name. It also supports high quality HDR to SDR conversion with fine-grained control, enabling everyone to enjoy HDR content on any display. To install mpv, execute: [source,shell] .... # pkg install mpv .... Here is a short sample [filename.]#~/.config/mpv/mpv.conf# [.programlisting] .... vo=gpu-next<.> gpu-context=wayland<.> hwdec=auto<.> screenshot-jpeg-quality=100 scale=ewa_lanczos4sharpest<.> dscale=ewa_lanczos4sharpest [TTRPG]<.> profile-cond=path:find('ttrpg')<.> profile=fast<.> save-position-on-quit=yes [hdr]<.> scale=bilinear dscale=bilinear dither=no correct-downscaling=no linear-downscaling=no sigmoid-upscaling=no hdr-compute-peak=yes hdr-peak-percentile=99.995 hdr-contrast-recovery=0.30 .... <.> Use the new gpu-next video output. A lot of features need this and/or provide higher quality when enabled <.> Wayland users should manually set this when seeing graphical glitches <.> Automatically detect if GPU hardware decoding is available and uses it <.> Best scaling algorithm. Disable if your hardware is not fast enough and videos start to skip frames <.> Example profile for long videos of recorded TTRPG sessions <.> Only apply when the path contains ttrpg <.> Use the builtin fast profile for lowest possible CPU/GPU usage <.> Example profile for users with a slow iGPU that still want to enjoy HDR content Example how a user with a iGPU would be able to watch HDR content with this sample config .... $ mpv --profile=hdr hdr_video.mkv .... For more examples on how mpv can be used, consult the mpv reference manual. [[smplayer]] === SMPlayer 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 install SMPlayer, execute: [source,shell] .... # pkg install smplayer .... [[vlc]] === VLC media player 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 install VLC, execute: [source,shell] .... # pkg install vlc .... [[kodi]] === Kodi (XBMC) 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] .... # pkg install kodi .... [[conferencing-meetings]] == Conferencing and Meetings 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. [[webcam-setup]] === Setting Up the Webcam To allow FreeBSD access to the webcam and perform its configuration it is necessary to install certain utilities: * 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. To install the required utilities, execute: [source,shell] .... # pkg install webcamd pwcview .... Enable the man:webcamd[8] service in `/etc/rc.conf` to start it at system boot: [source,shell] .... # sysrc webcamd_enable=YES .... The user must belong to the `webcamd` group. To add the user to `webcamd` group execute the following command: [source,shell] .... # pw groupmod webcamd -m username .... Since package:multimedia/webcamd[] needs the man:cuse[3] module this module must be loaded by executing the following command: [source,shell] .... # kldload cuse .... To load man:cuse[3] at system boot, execute the command: [source,shell] .... # sysrc kld_list+=cuse .... Once the utilities have been installed the list of available webcams can be shown with man:webcamd[8]: [source,shell] .... # webcamd -l .... The output should be similar to the following: [.programlisting] .... 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 Configure the available webcam executing the following command: [source,shell] .... # sysrc webcamd_0_flags="-N SunplusIT-Inc-HP-TrueVision-HD-Camera" <.> .... [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`, specifically the device identifier, and the entry in rc.conf might need to be updated. To avoid this issue either use the device name (`-N` option) and/or match with the device serial number if known (`-S` option) as displayed in the output of `webcamd -l`. For static devices, for example integrated laptop cameras, you can use the device identifier (`-d` option). ==== The man:webcamd[8] service must be started by executing the following command: [source,shell] .... # service webcamd start .... The output should be similar to the following: [.programlisting] .... Starting webcamd. webcamd 1616 - - Attached to ugen0.2[0] .... 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] .... % pwcview -f 30 -s vga .... Then package:multimedia/pwcview[] will display the webcam: image::pwcview.png[pwcview showing Absolute FreeBSD 3rd edition as an example] [[meetings-software-status]] === Meetings software status FreeBSD currently supports the following tools used to carry out videoconferences. .Meeting software [options="header", cols="1,1,1,1"] |=== | Name | Firefox status | Chromium status | Website | Microsoft Teams | Does not work | Works | link:https://teams.live.com[] | Google Meet | Works | Works | link:https://meet.google.com/[] | Zoom | Works | Works | link:https://zoom.us[] | Jitsi | Does not work | Works | link:https://meet.jit.si/[] | BigBlueButton | Does not work | Works | link:https://bigbluebutton.org/[] |=== [[scanners]] == Image Scanners 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 Before attempting any configuration it is important to check the scanner is supported by SANE. With the scanner connected, run the following command to get all connected USB devices: [source,shell] .... # usbconfig list .... The output should be similar to the following: [.programlisting] .... 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) .... Run the following command to obtain the `idVendor` and the `idProduct`: [source,shell] .... # usbconfig -d 3.2 dump_device_desc .... [NOTE] ==== Note here that the scanner is a plug-and-play device, and changing the USB port to which it is connected will change the output from `usbconfig list`. ==== The output should be similar to the following: [.programlisting] .... 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 .... -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. +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 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 .... [TIP] ==== 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. ==== After installing the necessary packages man:devd[8] must be configured to allow FreeBSD access to the scanner. Add the `saned.conf` file to [.filename]#/usr/local/etc/devd/saned.conf# with the following content: [.programlisting] .... 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"; }; .... <.> `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] .... # service devd restart .... The SANE backends include man:scanimage[1] which can be used to list the devices and perform an image acquisition. Execute man:scanimage[1] with `-L` argument to list the scanner devices: [source,shell] .... # scanimage -L .... The output should be similar to the following: [.programlisting] .... device `hpaio:/usb/Deskjet_1050_J410_series?serial=XXXXXXXXXXXXXX' is a Hewlett-Packard Deskjet_1050_J410_series all-in-one .... If man:scanimage[1] is not able to identify the scanner, this message will appear: [.programlisting] .... 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. To activate the service and have it run at boot execute the following command: [source,shell] .... # sysrc saned_enable=YES .... 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. .Graphical scanner programs [options="header", cols="1,1,1"] |=== | Name | License | Package | skanlite | GPL 2.0 | graphics/skanlite | GNOME Simple Scan | GPL 3.0 | graphics/simple-scan | XSANE | GPL 2.0 | graphics/xsane |===