Docs/Cc Transcoding.md

Installation and setup

First, you must determine on which machine of your network to install BubbleUPnP Server. In most cases it will be a desktop computer or a NAS. If you plan to transcode videos, you will need a powerful CPU or a supported GPU for hardware accelerated transcoding. A fast PC is recommended for pure software transcoding, especially for 1080p video. Many NAS will not be powerful enough (save for the most powerful ones). If you need to transcode only audio (including just audio in videos), any machine should be able to handle it.

The easiest way is to install BubbleUPnP Server on a Windows PC or on Ubuntu Linux (PPA package). It includes everything you need for Chromecast transcoding straight away, without requiring to configure anything. Just install it and it will be ready for use.

On other platforms, you must check these additional requirements:

ffmpeg/ffprobe

A working ffmpeg binary is required. The ffmpeg version must not be too old (at least v1.0) and the more up to date it is, the better.

A working ffprobe binary is optional. If a local ffprobe binary is not found, ffprobe will be called from the cloud, requiring that BubbleUPnP Server is passing the connectivity test succesfully.

  • ffmpeg/ffprobe binaries located in the installation directory are used if present, otherwise they are searched in the PATH
  • On Ubuntu, the PPA package will download the required ffmpeg/ffprobe binaries so it should work out of the box
  • On other Linux distributions, unzip these binaries in the installation directory
  • On the Raspberry Pi (powerful enough only for audio), the ffmpeg/ffprobe version might be too old and you must replace them by more recent binaries. This ffmpeg compilation guide may be useful
  • On other platforms you can try using Google for finding suitable ffmpeg/ffprobe binaries

The downloaded ffmpeg/ffprobe binaries must be executable:

chmod +x ffmpeg
chmod +x ffprobe

Whenever you update the ffmpeg/ffprobe binaries, you must restart BubbleUPnP Server for the change to take effect.

You can check what version of ffmpeg is used by looking at the BubbleUPnPServer.log.0 log file.

For full functionality, ffmpeg must include mp3 encoding support (libmp3lame), H264 support (libx264), Matroska support (libmatroska).

For transcoding media from Google Drive and more generally https streams, ffmpeg must be compiled with the https protocol (ffmpeg -protocols). That is often not the case with static builds of ffmpeg found online.

Playing media with Android BubbleUPnP

Android BubbleUPnP automatically detects BubbleUPnP Server on your network for Chromecast transcoding duties. There is no need to manually enter connection settings (unless you want to transcode to Chromecast [outside your local network]#cc_transcoding_outside).

When BubbleUPnP Server is detected, ‘More > gear icon > Chromecast > Current transcoding method’ will state so and display BubbleUPnP Server’s ip address.


Simply play any media to Chromecast normally. BubbleUPnP Server will perform transcoding in the background if and only if necessary. If the media cannot be transcoded or if there is any error, the original media will be forwarded as is to the Chromecast and might not play at all or partially (ex: video but no audio).

For best quality, BubbleUPnP Server only transcodes what is required: audio or video or both. For example, a MKV containing H264 video and DTS audio will be transcoded to a MKV containing the unmodified H264 video and the DTS audio track transcoded to MP3. In some cases, audio and video are both untouched and just remuxed in a different container.

Standalone audio (eg FLAC, WMA, …) is always transcoded to WAV, with no loss of quality.

Transcoding media outside the local network

It is possible to use transcoding features for use on the go, when you are not connected to your home local network. For example, if you visit a friend with your Chromecast and want to play on his TV a video that requires transcoding.

In that case, you must manually enter BubbleUPnP Server connection settings as explained here. When a remote BubbleUPnP Server is used, Settings > Chromecast > Version will show its ip address or hostname.

For technical reasons, only media reachable from the cloud can be transcoded by the remote BubbleUPnP Server. It includes:

  • your cloud media managed by Android BubbleUPnP: Google Drive, Dropbox, …
  • your home media exposed to Android BubbleUPnP via BubbleUPnP Server
  • any media that is stored online and that BubbleUPnP is able to handle

Any media that resides on your Android device or your friend’s local network cannot be transcoded by BubbleUPnP Server, because it cannot be reached.

Depending on the download bandwidth available on the target network and the upload bandwidth of your home network, you may have to decrease “Max video bitrate” substantially for the video to play smoothly (not stutter due to insufficient bandwidth).

GPU hardware accelerated video transcoding

BubbleUPnP Server can use your GPU to accelerate video transcoding with the following benefits:

  • much more efficient than pure software transcoding. Keep the CPU usage much lower, reducing noise (fans) in demanding scenarios and keeping the machine usable for other tasks
  • ability to transcode on a machine with a weak CPU (or even a powerful CPU but in a very CPU intensive scenario) but having a supported GPU
  • higher resolution transcodes with a target up to 1080p @60 fps for Chromecast Ultra and @30 fps for other models (vs 720p for software transcoding)

OS and GPU requirements

-Windows: modern NVIDIA cards starting from Kepler-based GeForce 600 Series, Intel CPU (since Sandy Bridge) or integrated Intel GPU supporting Quick Sync Video (QSV)
-Linux: same as Windows. See Linux section below for addtional requirements and setup instructions -macOS 10.8 or later: integrated Intel graphics supporting QSV (tested). Supposedly (untested): NVIDIA GPU, AMD GPU

ffmpeg requirement

A recent version of ffmpeg (v3.3+ recommended) compiled with proper GPU and hardware acceleration support is required. The ffmpeg version installed with Windows, macOS and Linux (Ubuntu package) installers fit this requirement.

Linux specific setup

You must use these ffmpeg binaries compiled with NVIDIA (tested) and Intel QSV support (untested). Most other precompiled (or stock distro) ffmpeg Linux binaries either do not have this support or are buggy (crash). Download and unzip into the BubbleUPnP Server installation directory (where BubbleUPnPServer.jar is found), and restart BubbleUPnP Server. Note that the Ubuntu BubbleUPnP Server package automatically installs these binaries.

These ffmpeg binaries require a 64-bit Linux install and at least glibc version 2.15. This should be the case, as glibc 2.15 was released in early 2012 and most Linux distributions released after that date have newer versions of the glibc.

NVIDIA:

You need at least version 378.13 of the NVIDIA binary drivers.

You can check your current driver version with:

$cat /proc/driver/nvidia/version

If you have installed the NVIDIA binary drivers from your distro repository (Ubuntu notably) they may be older and will not work with ffmpeg. In that case you will have to manually download and install NVIDIA drivers v378.13 or higher from their site, following carefully installation instructions.

Intel QSV:

You need to have the proper Intel drivers installed as well as the Kernel supporting QSV. The ffmpeg build has Intel QSV support (for CPUs limited to: Haswell, Broadwell, Skylake) but it is currently untested.

Operation

BubbleUPnP Server will automatically attempts GPU transcoding if the requirements are met. Otherwise, or if GPU transcoding fails for whatever reason and nothing was transcoded yet, BubbleUPnP Server will fallback to software transcoding.

To check if your setup is suitable for GPU transcoding, you can perform a transcoding test in ‘Settings > Chromecast Transcoding’.

You can disable GPU transcoding entirely by unchecking ‘Settings > Chromecast Transcoding > Use GPU hardware accelerated transcoding’. It is recommended to leave it enabled unless you really prefer software transcoding, or to perform comparisons between software and GPU transcoding.

BubbleUPnP Server can perform either a full (decode+encode) or partial (encode only) GPU transcoding, depending on the input video and GPU features. GPU decoding support is as follow:

All GPU encoding is done using h264 which is universally supported.

Only one GPU transcoding task is possible at the time. If BubbleUPnP Server must handle a new transcode while a GPU transcode is already active, it will fallback to software transcoding for that new transcode.

How can I determine GPU support for my setup ?

Start the BubbleUPnP Server web config, go into ‘Settings > Chromecast Transcoding’ and tap the ‘Peform GPU transcoding test’ button. After a few seconds (up to a minute), it will display if GPU transcoding is supported and if the case which GPU is used and its support for decoding various codecs.

How can I tell if GPU transcoding is used ?

1 Play with Android BubbleUPnP a video to your Chromecast that you know requires transcoding.
2 While the video is playing, In the BubbleUPnP Server web config, perform the GPU transcode test in ‘Settings > Chromecast Transcoding’. 3 => It should fail doing the test and report “GPU is currently in use”.

How can I measure the gain of GPU transcoding (vs software transcoding) on CPU usage ?

Follow these instructions to first check CPU usage with pure software transcoding, then with GPU transcoding:

  1. start the BubbleUPnP Server web config and disable GPU transcoding by unchecking ‘Settings > Chromecast Transcoding > Use GPU hardware accelerated transcoding’
  2. start Android BubbleUPnP
  3. in Android BubbleUPnP settings, verify that BubbleUPnP Server is recognized for transcoding in ‘Settings > Chromecast’
  4. play a video that you know requires (video) transcoding to your Chromecast, or temporary force transcoding in ‘Settings > Chromecast > Force transcode’ (do not forget to disable it later!)
  5. On the machine that runs BubbleUPnP Server, monitor the ffmpeg process CPU usage (as ffmpeg performs pure software transcoding)
  6. Now, in BubbleUPnP Server web config enable ‘Settings > Chromecast Transcoding > Use GPU hardware accelerated transcoding’. If using Android BubbleUPnP 2.8.10+, verify that ‘Settings > Chromecast > Use GPU transcoding’ is enabled
  7. play the same video and monitor the ffmpeg process CPU usage (as ffmpeg may now use GPU transcoding if possible)
  8. => if GPU transcoding is effective, CPU usage should be much lower in the second play. Note that if partial (encode only) GPU transcoding is performed, ffmpeg CPU usage can still be high. When full (decode+encode) GPU transcoding is in effect, CPU usage should be very low

Troubleshooting

Video stuttering issues

First, it is important to understand that some videos have very high bitrates requiring too much network bandwidth that the Chromecast WiFi cannot handle, causing stutter.

And unlike wired networks such as Ethernet, WiFi is bad at sustaining stable bandwidth over time: it is usually very spiky and irregular.

For best performance and for media not stored on your Android device, make sure that the machine running your UPnP/DLNA Media Server managing your media use a wired (Ethernet) connection to your WiFi router. If that is a PC or a NAS, make sure that it is not connected through WiFi as this will degrade network performance for streaming significantly.

Videos causing stutter will be in most cases high definition videos such as 1080p. Most cameras on current phones take 1080p videos at very high bitrates and enter in the problematic category. Stuttering can start to apppear with video bitrates higher than 8000 Kbps (1000 KB/s) and maybe even lower depending on the WiFi quality.

To reduce network bandwidth and eliminate stutter, BubbleUPnP can force transcode videos whose bitrate is higher than a user configured bitrate (the “Max video bitrate” setting). For example, suppose you play a 1080p h264 video whose bitrate is 16000 Kbps. If “Max video bitrate” is set to 8000 and “Enforce max bitrate” is enabled, this will force a reencode to 8000 Kbps, because 16000 > 8000.

But transcoding a video to reduce network bandwidth can potentially cause stutter if the CPU is not fast enough to perform the transcoding. Transcoding a 1080p video requires a lot of CPU power and most current PCs are able to handle it. But if the CPU is not fast enough, video will stutter because it cannot be transcoded fast enough.

To troubleshoot stutter issues, follow these steps for a possible solution:

On the machine running BubbleUPnP Server, monitor the ffmpeg process CPU usage (using the task manager on Windows), while the stuttering video is playing:

  1. the ffmpeg process is not running (no transcoding is performed). The cause of stuttering is that the video bitrate is too high:
    • Make sure “Enforce max bitrate” is enabled
    • lower “Max video bitrate” to 5000 Kbps and play the video again
    • if the video still stutters
      • lower “Max video bitrate” to 2000 Kbps and play the video again
      • if the video still stutters, go to 3. to check if the CPU is maxed out
  2. the ffmpeg process is running and its CPU usage is not close to 100% (transcoding is performed, CPU not maxed out). The cause of stuttering is that the video bitrate is too high:
    • lower “Max video bitrate” to 5000 Kbps and play the video again
    • if the video still stutters:
      • lower “Max video Bitrate” to 2000 Kbps and play the video again
      • if the video still stutters the cause of the stutter is unknown and neither due to bandwith nor to the CPU usage
  3. the ffmpeg process is running and its CPU usage is close to 100% (transcoding is performed, CPU maxed out). The cause of stuttering is that the CPU is maxed out:
    • to lower CPU usage, set “Video encoding speed” to “Ultra fast” and play the video again
    • if CPU usage:
      • is still at 100%: disable transcoding by setting a high value (such as 30000) for “Max video bitrate” and play the video again. if it still stutters there is no solution as the video requires too much bandwidth and your CPU is not powerful enough to lower it
      • is below 100% but video still stutters: go to 2

Android BubbleUPnP doesn’t detect BubbleUPnP Server

If you installed BubbleUPnP Server and Android BubbleUPnP doesn’t detect it (Chromecast settings remain grayed out):

  • in the BubbleUPnP Server web config, verify that 'Settings > Chromecast Transcoding > Enable Chromecast transcoding' is enabled
  • make sure that a firewall running on the machine on which BubbleUPnP Server runs is not blocking UDP port 1900
  • on Windows, check that BubbleUPnPServer.exe is not blocked by the firewall
  • reboot your WiFi router and Android device

Some or all videos managed by Windows Media Player do not play

There is a known issue with WMP. The symptom is that the Chromecast will show the video loading screen for a few seconds before reverting to the BubbleUPnP logo.

The cause is unclear and until there is a solution, it is suggested to use another Media Server such as Serviio