Smart Transcode

Troubleshooting: bare metal

For the Linux service installed with install.sh. Everything runs as the systemd unit smart-transcode; the program is in /opt/smart-transcode and the data in /var/lib/smart-transcode (unless you chose another --data-dir).

First: look at the service

systemctl status smart-transcode            # running? since when? last error lines
journalctl -u smart-transcode -n 100 --no-pager
journalctl -u smart-transcode -f            # follow live
ls -l /var/lib/smart-transcode              # transcode.log, diagnostics.log, transcode_history.db
tail -f /var/lib/smart-transcode/transcode.log

The unit restarts itself if the program crashes (every 5 seconds), so a repeating error in the journal means it is failing at start-up. Also useful: ps -o user,uid,gid,cmd -C uvicorn shows which user and numeric IDs the service runs as.

I cannot open the page

  • Is it running and listening? systemctl is-active smart-transcode and ss -ltnp | grep 8080 (use your port; it is in the unit file: grep ExecStart /etc/systemd/system/smart-transcode.service).
  • Address already in use. Another program has the port. Reinstall with another port (sudo ./install.sh --uninstall, then sudo ./install.sh --port 8090 --media …) or stop the other program.
  • Firewall. On firewalld systems: sudo firewall-cmd --add-port=8080/tcp --permanent && sudo firewall-cmd --reload. On ufw: sudo ufw allow 8080/tcp.
  • Test locally first: curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/api/auth/me should print 200. If it does but other machines cannot connect, it is the firewall or the network.
  • It failed to start after a system upgrade. The Python environment may be out of step with the system's Python. Run sudo ./upgrade.sh from the package: it rebuilds the environment.

My GPU is not listed (or conversions use the CPU)

The service uses whatever ffmpeg is on the machine, run as the service user.

ffmpeg -hide_banner -encoders | grep -E "nvenc|vaapi|qsv|x265"     # which encoders this ffmpeg has
sudo -u USER ffmpeg -hide_banner -encoders | grep -c nvenc          # USER = the account the service runs as
  • The encoder is missing from ffmpeg. Distribution ffmpeg packages often lack NVENC or QSV. On RHEL-family systems install ffmpeg from RPM Fusion; elsewhere use a fuller build. Or use the Docker image, which includes everything.
  • NVIDIA: nvidia-smi must work, and ffmpeg must have hevc_nvenc. After a driver update, reboot (or reload the modules) and press Re-detect in Settings → Video.
  • Intel / AMD (VA-API): ls -l /dev/dri should show a renderD128; vainfo (package libva-utils) should list HEVC encode (VAEntrypointEncSlice). Install the driver: intel-media-driver (Intel) or mesa-va-drivers (AMD; on RHEL-family mesa-va-drivers-freeworld from RPM Fusion). The unit adds the service to the groups that own /dev/dri by itself; check sudo -u USER test -r /dev/dri/renderD128 && echo ok. With several GPUs set the right node: edit SMART_TRANSCODE_VAAPI_DEVICE= in /etc/smart-transcode.env and sudo systemctl restart smart-transcode.
  • Press Re-detect in Settings → Video after any change. A GPU encoder is tested on a tiny clip the first time it is needed.

Permission denied, empty library or wrong file owner

The service must run as a user (uid and gid) that may write your media. Compare:

stat -c '%u:%g  %U:%G  %a' /srv/media                            # who owns the media
ps -o user,uid,gid -p $(systemctl show -p MainPID --value smart-transcode)   # who the service runs as
sudo -u USER test -w /srv/media && echo writable || echo NOT writable

Fix by running the service as the owner (sudo ./install.sh --uninstall, then sudo ./install.sh --media /srv/media), or by giving the account access (sudo setfacl -R -m u:USER:rwx -d -m u:USER:rwx /srv/media). Full explanation: User and group IDs.

  • SELinux (Fedora, RHEL and derivatives) can block a service from files it may otherwise access: getenforce, then sudo ausearch -m avc -ts recent. For media on a non-standard path label it for the service or use a policy that allows it (chcon -R -t public_content_rw_t /srv/media is a quick test).
  • Network shares: mount with the right uid=/gid= (SMB) or matching numeric IDs (NFS).
  • Data folder: must belong to the service user: ls -ld /var/lib/smart-transcode. “unable to open database file” means it does not, or the disk is full or read-only.

Conversions fail

  • Open the file's status in History for the attempts and ffmpeg's messages. Run the shown ffmpeg command by hand as the service user to reproduce it.
  • Not enough free space: df -h on the media disk. The new file is written next to the original, so a file needs about its own size free during conversion.
  • The converted file never replaces the original. The user cannot write the folder (see above).
  • Raise logging to DEBUG in Settings → Debug while you reproduce it, then read transcode.log.

Upgrade problems and rollback

  • upgrade.sh backs up first and puts the old version back by itself if the new one does not start. Its log is the /tmp/smart-transcode-upgrade.*.log file it names.
  • Restore a backup by hand: sudo ./upgrade.sh --rollback smart-transcode-1.0-<time>.tar.gz (files are in /var/backups/smart-transcode/; database snapshots are in its database/ folder).
  • Installer log after a failed install: the /tmp/smart-transcode-install.*.log file it names.

Starting over

sudo ./install.sh --uninstall                  # removes the service and program, keeps the database
sudo ./install.sh --uninstall --purge-data     # also deletes the database and logs

Your media files are never touched by uninstalling.