This page is about configuring Kodi on a Raspberry Pi installed with RaspiOS, to be used as NAS and mediacenter. See the main index at Home Mediacenter and NAS with the Raspberry Pi.

Debian 11 Bullseye includes Kodi 19.1 or 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:

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

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 this picture.

Check for other unnecessary configuration options in /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.

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:

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

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:

systemctl stop dphys-swapfile.service
systemctl disable dphys-swapfile.service

• Kodi on Bullseye RPiOS
• Kodi on Raspberry Pi OS / Raspbian Buster (not Bullseye!)
• Full KMS vs Fake KMS vs Legacy driver
• arm_boost
• Bullseye bonus: 1.8GHz Raspberry Pi 4

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 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.

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

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:

[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

The service must be enabled and started:

systemctl enable kodi.service
systemctl start kodi.service

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:

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

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:

systemctl restart polkit.service 
systemctl restart kodi

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

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

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.

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

http://sirius.shoutca.st:8713/stream

• 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.

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.

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:

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

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

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 vcgencmd command:

#!/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

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

# 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

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 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:

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

Missing support is confirmed also by the Video4Linux library:

v4l2-ctl -d 10 --list-formats-out

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 1366×768 pixels and a bitrate of 6000 kbit/s (about 3 Gb per hour):

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

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 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 LibreELEC 10.0 Beta, which packs Kodi 19.0 over Linux Kernel 5.10.17 Using Raspberry Pi OS, I had to downgrade the kernel to 4.19 to fix the issue.

• MPEG-4 videos play jerky in Kodi with kernel 5.10
• MPEG-4 video jerky on Raspberry Pi 4
• [Guide] Kodi on Raspberry Pi OS / Raspbian Buster
• Playing video on the Raspberry Pi
• What codecs can it play?
• vcgencmd

Beside Kodi, which has its own functions to play music, I want also the functions offered by the 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.

I have developed bot the photo-reframe Slideshow standalone program and the 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 1360×768 pixels, Kodi interface runs at 1280×720 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.

How to start it from Kodi?