rigacci.org

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Kodi on a Raspberry Pi NAS ======

This page is about configuring **[[wp>Kodi_(software)|Kodi]]** on a Raspberry Pi installed with RaspiOS, to be used as NAS and mediacenter. See the main index at **[[raspberrypi_nas]]**.

===== RaspiOS 11 Bullseye =====

**Debian 11 Bullseye** includes Kodi 19.1 or [[https://packages.debian.org/bullseye-backports/kodi|Kodi 19.4 as a backport]]; the derivative **RaspiOS** includes Kodi 19.4 natively instead. Default installation on the **Raspberry Pi 4** of the Raspberry Pi OS based on **Debian 11 Bullseye** is rather satisfactory in terms of optimization; no special settings are required in **raspi-config** nor tweaking of **/boot/cmdline.txt** or **/boot/config.txt**.

If your system has undergone some software upgrades, it is recommended to check the content of **config.txt** for obsolete or wrong settings. This is the default content after a vanilla installation:

<file>
dtparam=audio=on
camera_auto_detect=1
display_auto_detect=1
dtoverlay=vc4-kms-v3d
max_framebuffers=2
disable_overscan=1

[cm4]
otg_mode=1

[pi4]
arm_boost=1
</file>

The **vc4-kms-v3d** overlay is particularly important. The GPU of the **Pi 4** is a **VideoCore VI** capable of **OpenGL ES 3.2**, this requires a specific driver, different from the one required e.g. by the Raspberry Pi 3, which has a VideoCore IV GPU capable only of OpenGL ES 2.0. The codename of the driver is **VC4** for the old GPU and **V3D** for the newer one. Loading the **vc4-kms-v3d** overlay, the device tree sorts out which exact node is enabled, be it VC4 or VC6. They both get aliased to "v3d", therefore the overlay will enable the right variant for the board.

The **legacy KMS driver** developed for the Raspberry up to version 3 does not work with the newer Pi 4, because video acceleration support was removed from the hardware (the Pi4 is powerfull enough to do 3D video and OpenGL in software). Operating system before Debian 10 Buster required the now obsolete **vc4-fkms-v3d** overlay on the **Raspberry Pi 4**, i.e. the //Fake Kernel Mode Setting// (a software driver based on the now obsoleted DispmanX Broadcom API), because at that time it was the best option. Now we should go with the Linux standard APIs **vc4-kms-v3d**.

Another usefull option is **arm_boost=1**, which works only on some more recent Raspberry Pi 4: it enable the increase of the clock rate from 1.5 GHz to 1.8 GHz. Not all the Pi 4 are able to swith to 1.8 GHz, only the ones witht the three components highlighted into the **{{.:raspberrypi:raspberry-pi-white-ring-500x592.png?linkonly|this picture}}**.

Check for other unnecessary configuration options in **[[https://www.raspberrypi.com/documentation/computers/config_txt.html|/boot/config.txt]]**, like **start_x=1** needed on the Pi 3 to play VP6, VP8, Theora and alike encoded files. Kernel options added into **/boot/cmdline.txt** may be obsolete too, e.g. the **elevator=deadline** was suggested as an alternative to the //cfq// scheduler when minimizing I/O latency is more important than maximizing I/O throughput, but it does not exist in recent Linux kernels in Bullseye.

==== Swap file ====

The default RaspiOS installation will enable a swap file to support system memory. Using the **free** command you can see that a 100 Mb swap file was enabled:

<code>
               total        used        free      shared  buff/cache   available
Mem:         3931052      274392       55828      105748     3600832     3397328
Swap:         102396      102396           0
</code>

The swap file is **/var/swap** and unfortunately it is on the very slow **SD card**. Having 4 Gb of RAM it is preferable to disable the swap file at all, just using the systemd **dphys-swapfile** service:

<code>
systemctl stop dphys-swapfile.service
systemctl disable dphys-swapfile.service
</code>

==== Web References ====

  * **[[https://forums.raspberrypi.com/viewtopic.php?t=323303|Kodi on Bullseye RPiOS]]**
  * **[[https://forums.raspberrypi.com/viewtopic.php?f=66&t=251645|Kodi on Raspberry Pi OS / Raspbian Buster]]** (not Bullseye!)
  * **[[https://forums.raspberrypi.com/viewtopic.php?t=255478|Full KMS vs Fake KMS vs Legacy driver]]**
  * **[[https://forums.raspberrypi.com/viewtopic.php?t=325836|arm_boost]]**
  * **[[https://www.raspberrypi.com/news/bullseye-bonus-1-8ghz-raspberry-pi-4/|Bullseye bonus: 1.8GHz Raspberry Pi 4]]**

===== RaspiOS 10 Buster =====

I installed my Raspberry Pi 4 NAS/mediacenter starting with **RaspiOS** based on **Debian 10.8 Buster**. The distribution provides **Kodi 18.7 Leia**. Kodi offers a nice interface to watch videos, photos, listening to music, streaming radio, etc. Sometimes I want to listen music with the monitor turned off, so I decided to install also **Music Player Daemon**, which has a nice **client app** for the Android smartphone and also a **command line client**. Finally I wish also to use **[[https://github.com/RigacciOrg/photo-reframe-slideshow|photo-reframe Slideshow]]**, a program that I wrote to view pictures at full monitor resolution and with on-the-fly pan/zoom at prefixed geometry for each picture.

==== Raspberry Pi OS Config ====

Using the **raspi-config** tool, we configured the following:

  * Advanced Options => GL Driver
    * Raspberry Pi 3: GL (Full KMS)
    * Raspberry Pi 4: GL (Fake KMS)\\ ''dtoverlay=vc4-kms-v3d'' in /boot/config.txt
  * Performance Options => GPU Memory => 320\\ ''gpu_mem=320'' in /boot/config.txt

===== Kodi =====

Installed the packages:

  * **kodi**
  * **kodi-bin** - Contains the executable **kodi-standalone**, which is the one to execute.
  * **kodi-peripheral-joystick** - Necessary to add support for the gamepad.
  * **kodi-eventclients-kodi-send** - Contains the **kodi-send** tool, used to control Kodi from the command line.

We create an user called **kodi** which belongs to the groups: **audio**, **video**, **input**, **pulse** and **pulse-access**. To execute kodi as a Systemd service we created an Unit file **/etc/systemd/system/kodi.service**:

<file>
[Unit]
Description = Kodi Media Center

# if you don't need the MySQL DB backend, this should be sufficient
After = systemd-user-sessions.service network.target sound.target

# if you need the MySQL DB backend, use this block instead of the previous
# After = systemd-user-sessions.service network.target sound.target mysql.service
# Wants = mysql.service

[Service]
User = kodi
Group = kodi
Type = simple
ExecStart = /usr/bin/kodi-standalone
Restart = always
RestartSec = 15

[Install]
WantedBy = multi-user.target
</file>

The service must be enabled and started:

<code>
systemctl enable kodi.service
systemctl start kodi.service
</code>

==== Kodi Power Options ====

I want to be able to **poweroff** or **reboot** the mediacenter using the **Kodi Power Menu**, but having installed Kodi as above, only the **Exit** option is present in that menu. To enable the other options it is necessary to install the package:

  * **acpi-support**

Then I created the file **/var/lib/polkit-1/localauthority/50-local.d/custom-actions.pkla** with this content:

<file>
[Actions for kodi user]
Identity=unix-user:kodi
Action=org.freedesktop.login1.*;org.freedesktop.consolekit.system.*
ResultAny=yes
ResultInactive=no
ResultActive=yes
</file>

That policy allows the kodi user to execute two types of actions (**login1** and **consolekit.system**), all that types contain actions like restart, but it seems that Kodi uses the first one.

Finally I restarted the services:

<code>
systemctl restart polkit.service 
systemctl restart kodi
</code>

Doing so, the Power Menu now has the following items:

  * Exit
  * Power off system
  * Custom shutdown timer
  * Reboot


==== Kodi Add-ons ====

We don't want to depend on auto-download, audo-updates, etc. So we manually download the zip file for each app-on on the local filesystem. To allow installation in this way, it is required to enable **System Settings** => **Add-ons** => **Unknown sources**. Finally we can do **Kodi Main Manu** => **Add-ons** => **My add-ons** => **Install from zip file**.

Despite installing the add-on from a zip file, any **required add-ons** not present into the system will be automatically downloaded from the net and installed. Fortunately you can find the zip files of this additional add-ons into the **$HOME/.kodi/addons/packages/** directory, so you can backup them for later use.

==== Radio/audio streaming ====

Create a **.strm** file containing the URL, like this:

<file>
http://sirius.shoutca.st:8713/stream
</file>

=== Where to place the file ===

   * **Music** - If the .strm file is placed into a //Music// folder, the NFO file is ignored; tags included into the stream will be displayed by the player. The stream file is not added into the audio library (may be because we use only the local metadata source).
   * **Music videos** or **Movies** - If the .strm file is placed into a //Music videos// or //Movies// folder you can add an NFO file of the appropriate type. In that case the //title//, //plot// and //artist// tags are shown into the info dialog box and into the player, but tags embedded into the streams are ignored. Unfortunately, once the file is played and you go back to the wall view, the title is replaced by the path part of the URL.

=== Thumbnail ===

It is possibile to add a .tbn file witht the same name of the .strm one; that file (JPEG or PNG) will be used as thumbnail for the stream.

=== Ignore SSL certificate ===

If the data is streamed over **HTTPS**, but a **bad certificate** is provided (self signed or with errors), the stream does not play and Kodi will log something like this:

<code>
ERROR: CCurlFile::Stat - Failed: SSL peer certificate or SSH remote key was not OK(60) for https://...
</code>

To circumvent the problem you can add the **%%|verifypeer=false%%** suffix to the URL.

===== Video codecs and jerky videos =====

To make a long story short: I had to **downgrade the kernel** from **5.10** (as shipped with RaspiOS 2021-01-11 Buster) to the old **4.19**, otherwise there is a bug hitting Kodi and MPEG-4 video files. Here it is the long story I had to learn...

Coding and decoding of video streams is a very complex task; software used for that purpose (known as //codecs//) can be embedded into the hardware (generally into the GPU) or can be installed as a software libraries. Unfortunately many video formats (codec algorithmas) are not open and there are not free implementations of them, so you have to buy a license to install the library or to unlock the function inside the hardware.

To know what codecs are enabled into the **VideoCore GPU** of the Raspberry Pi you can use the **[[https://www.raspberrypi.org/documentation/raspbian/applications/vcgencmd.md|vcgencmd]]** command:

<code bash>
#!/bin/sh
CODECS="AGIF FLAC H263 H264 MJPA MJPB MJPG MPG2 MPG4 MVC0 PCM THRA VORB VP6 VP8 WMV9 WVC1"
for CODEC in $CODECS; do
    vcgencmd codec_enabled "$CODEC"
done
</code>

Some codecs (FLAC, THRA, VORB, VP6 ad VP8) are disabled per default, but they can be enabled with some options in **/boot/config.txt**:

<code>
# Memory reserved for the GPU.
gpu_mem=320
# Firmware files transferred to the GPU prior to booting;
# on the Pi4, load the start4x.elf and fixup4x.dat files.
start_x=1
</code>

Unfortunately codecs **H263** and **MPG4** remains **disabled** in the **Raspberry Pi 4**, whereas they are enabled on the Raspberry Pi 3. Codecs H263 and MPG4 are enabled into the Raspberry Pi 3 because they are payed (price included into the hardware cost), if you want to enable additional codecs (e.g. MPG2 or WVC1) you have to [[https://codecs.raspberrypi.org/|purchase a license key]] that is tied to your hardware serial number and must be written into ''/boot/config.txt''.

The FAQ says that on the Pi 4, hardware support for MPEG2 and VC-1 codecs has been removed because the processor is powerful enough to decode these in software (buying a license is not longer an option), but my experience is very bad with videos in **MPG4** format (e.g. the ones produced by the **XviD** library). The videos play **unacceptably jerky**, and Kodi says this into the log:

<code>
NOTICE: VideoPlayer::OpenFile: /data/videos/family/2018-08_greece.mkv
NOTICE: Creating InputStream
NOTICE: Creating Demuxer
NOTICE: Opening stream: 0 source: 256
NOTICE: Creating video codec with codec id: 12
 ERROR: CMMALVideo::Open Failed to commit format for decoder input port
        vc.ril.video_decode:in:0(MP4V) (status=3 EINVAL)
NOTICE: CDVDVideoCodecFFmpeg::Open() Using codec: mpeg4
NOTICE: Creating video thread
NOTICE: running thread: video_thread
</code>

Missing support is confirmed also by the Video4Linux library:

<code>
v4l2-ctl -d 10 --list-formats-out
</code>

Probably this is the cause of **videos playing jerky** on my Raspberry Pi 4, whereas they played smoot on the old Raspberry Pi 3 :-(

I exprienced that problem (**unacceptable video playbak performance**) with several videos encoded with the **XviD library**. They are videos at **1366x768** pixels and a bitrate of **6000 kbit/s** (about 3 Gb per hour):

<code>
Format                     : MPEG-4 Visual
Format profile             : Advanced Simple@L4
Format settings, Matrix    : Default (H.263)
Codec ID                   : V_MPEG4/ISO/ASP
Frame rate                 : 29.970 (30000/1001) FPS
Writing library            : XviD 67
</code>

Hardware support for MPG4 is **permanently disabled** into the RPi 4, so what to do? The FAQ says that the CPU power of the RPi4 is enough to perform the decoding entirely in software; indeed the problem does not exist in **[[https://libreelec.tv/|LibreELEC 9.2]]**, which packs Kodi 18.9 over Linux Kernel 4.19.x; playing the same jerky videos is perfectly smooth in that environment. The problem does not exist even in **[[https://libreelec.tv/raspberry-pi-4/|LibreELEC 10.0 Beta]]**, which packs Kodi 19.0 over Linux Kernel 5.10.17 Using Raspberry Pi OS, I had to **[[raspberrypi_kernel_upgrade_downgrade|downgrade the kernel]]** to 4.19 to fix the issue.

  * **[[https://github.com/raspberrypi/linux/issues/4257|MPEG-4 videos play jerky in Kodi with kernel 5.10]]**
  * **[[https://www.raspberrypi.org/forums/viewtopic.php?f=28&t=308168|MPEG-4 video jerky on Raspberry Pi 4]]**
  * **[[https://www.raspberrypi.org/forums/viewtopic.php?f=66&t=251645|[Guide] Kodi on Raspberry Pi OS / Raspbian Buster]]**
  * **[[https://www.raspberrypi.org/documentation/usage/video/|Playing video on the Raspberry Pi]]**
  * **[[https://www.raspberrypi.org/documentation/faqs/README.md#pi-video-codecs|What codecs can it play?]]**
  * **[[https://www.raspberrypi.org/documentation/raspbian/applications/vcgencmd.md|vcgencmd]]**

===== Playing music with MPD =====

Beside Kodi, which has its own functions to play music, I want also the functions offered by the **[[https://www.musicpd.org/|Music Player Daemon]]**; so I installed the Debian packages:

  * **mpd** - The Music Player Daemon, the underlying daemon which actually plays music.
  * **ncmpc** - It is a MPD client for text terminals, based on ncurses.

===== photo-reframe-slideshow =====

I have developed bot the **[[https://github.com/RigacciOrg/photo-reframe-slideshow|photo-reframe Slideshow]]** standalone program and the **[[https://github.com/RigacciOrg/script.picture.photo-frame|script.picture.photo-frame]]** add-on for Kodi. Both programs provide the ability to **play a slideshow** of your photos at full screen and **with on-the-fly pan/zoom** configured for each image, based on a playlist.

Unfortunately the Kodi add-on **does not use the native monitor resolution**, e.g. if the monitor is **1360x768 pixels**, Kodi interface runs at **1280x720** and the images will be resized at Kodi interface resolution and then stretched to fit the screen; this is obviously sub-optimal. I figured it out with **Kodi 17.6 Krypton**, please let me know if something better happens in other releases. Another limitation of a Kodi add-on is that I can **execute it only from the contextual menu** over a pictures folder, not the most intuitive approach.

FIXME How to start it from Kodi?