What it does
FCast is an open protocol for sending audio and video from one device to another — the same job as Chromecast or AirPlay, without the closed ecosystem. Anyone can write a sender or a receiver.
This add-on turns Kodi into an FCast receiver. It listens on TCP port 46899
and advertises itself over mDNS as _fcast._tcp, so senders on the same network
find it by themselves. Senders that cannot discover it can be pointed at the box by IP address.
-
Video and audio
DASH, HLS and direct streams, with the HTTP headers the sender attaches — so streams from CDNs that check
RefererorUser-Agentplay. -
Photos
Cast pictures go to Kodi's picture viewer, downloaded before they are shown so the screen never goes black waiting, and they hold off the screensaver while they are up.
-
Queues that move
The receiver reports each item as it finishes, so a sender's own queue advances. It also walks playlists handed to it whole, pictures included.
-
Two-way control
Volume, seek, pause and playback speed in both directions, and several senders stay in step with each other through
PlayUpdate.
Tested senders. Grayjay, the official FCast senders, and CastLab for Android (beta — see Troubleshooting).
Install
You need Kodi 21 (Omega) or newer, and
inputstream.adaptive 21.5.9 or newer for HLS and DASH streams.
Which version will I get? The repository serves the last proper release. The v3 work described above — photos, playlists, volume — is in p0.9.9-pre, a hand-installed zip until it has had some feedback. Install the repository regardless: it is what brings you the release when it lands, without your having to come back here.
From the add-on repository recommended
Installing the repository once lets Kodi update the receiver on its own, on every device.
-
In Kodi, allow add-ons from unknown sources:
Settings → System → Add-ons → Unknown sources -
Download the repository zip:
repository.fcast.ozankiratli-1.0.0.zip Downloading on the Kodi box itself? Kodi's own file browser can reach this URL directly in step 3. - Settings → Add-ons → Install from zip file, and pick that zip
- Settings → Add-ons → Install from repository → FCast Receiver Repository → Services → FCast Receiver
That is it — the service starts with Kodi. Kodi then checks for new versions on its own schedule, as long as Settings → System → Add-ons → Updates is set to Install updates automatically.
From a zip
Grab the add-on zip from the releases page and use Settings → Add-ons → Install from zip file. Updates are then yours to do by hand.
Already running a zip install? A zip install has no repository behind it, so Kodi has nothing to check for new versions. Install the repository as above and Kodi picks up newer releases for the add-on you already have — there is no need to uninstall it first.
Test builds
p0.9.9-pre — the full v3 protocol try this
This is the build worth running. The receiver used to hold a connection to a modern sender only by luck, and did little once it had one. It now implements FCast v3 and announces itself as such, and the parts that were missing or half-working do their job:
- Volume, in both directions. A sender can set the volume on the box, and a change made on the box goes back to the sender. Playback speed too, clamped to the 0.8×–1.5× Kodi supports rather than failing outside it.
- Queues that move on. The receiver reports each item as it finishes, with the item attached — a report with nothing in it tells the sender nothing, which is why Grayjay's queue used to strand on the video that had just ended.
- Playlists. A sender can hand over a whole queue and the receiver walks it itself: offset, per-item volume and speed, jumping between items, and a duration for pictures so a photo in a queue moves on by itself.
- Photos that actually appear. Cast pictures went to the video player, which showed them for a few milliseconds and closed. They go to Kodi's picture viewer now, downloaded before they are shown so the screen never goes black waiting, and they hold off the screensaver while they are up.
-
Senders that join late. The
Initialhandshake tells a sender what is already on screen when it connects, andPlayUpdatekeeps several senders in step with each other. - Settings. A configuration screen of its own — notifications, picture downloading, keeping the screen awake, picture duration. See the manual.
- Failures you can see. Everything used to be logged at debug level, which Kodi hides, so a failed download or discovery that never registered looked exactly like working. Those are warnings now, and connections are logged as they happen.
Download p0.9.9-pre Release notes
Install it with Settings → Add-ons → Install from zip file. Already have the add-on? Install the zip over it; there is nothing to uninstall first.
Feedback is what this is waiting for. The build stays a test build until it has had some. Once it has, the same code goes out as a proper release through the add-on repository, and every device that installed the repository picks it up on its own.
Anything odd — a sender that will not connect, a photo that never appears, a queue that stops — is worth an issue on GitHub, with the log lines from Reading the log.
How test builds work
Builds marked pre-release on the releases page are never published to the add-on repository, so no installed Kodi is offered one as an update — you install the zip by hand if you want to try it.
Their version carries a ~ — this one is 0.9.9~pre — which Kodi
sorts below the release that follows it. So the real release supersedes a test build
on its own, through the repository, with nothing to uninstall.
Manual
Casting to Kodi
Leave Kodi running. In your sender — Grayjay, an official FCast sender, CastLab — open the cast menu and the Kodi box appears in the device list, named after the machine. Pick it, and what you were watching starts on the television.
Nothing found in the list? The sender is not seeing the mDNS advertisement. Every sender can
also connect straight to an address: enter the Kodi machine's IP and port 46899
by hand. See Discovery below.
One Kodi setting worth changing
Settings → Player → Videos → Sync playback to display — set to On. Playback speed control from a sender depends on it.
Add-on settings
Settings → Add-ons → My add-ons → Services → FCast Receiver → Configure
- Show on-screen notifications
- The messages shown when a sender connects, disconnects, or starts something playing. Turn them off to keep the screen clear; errors are always shown regardless.
- Download pictures before showing them
- Kodi's picture viewer clears the screen the moment it is told to show something else, so casting a second photo used to leave the screen black for the length of the download. With this on, the picture already up stays there while the next one is fetched, and they swap when it is ready. The last dozen pictures are kept, so stepping back through a slideshow, or casting the same photo twice, downloads nothing again. Turn it off to hand the URL straight to Kodi.
- Keep the screen awake while a picture is showing
- Kodi treats a single picture as an idle screen rather than as something playing, so its screensaver starts up behind the picture, cannot come to the front past the picture viewer, and on some skins that refusal is audible. With this on, a picture on screen counts as the box being in use. Turn it off to let the screen sleep over a cast picture.
- Picture duration (seconds)
-
How long a picture in a cast playlist stays on screen before the queue moves on.
A sender that asks for a duration of its own gets it, unless
Ignore the duration the sender asks for is set. Zero leaves each picture up until the
sender moves on.
A picture cast on its own is never closed automatically, whatever this is set to. It stays up until a sender stops it, or you close it from Kodi.
Reading the log
Connections and failures are logged. To see everything the add-on has to say, turn on Settings → System → Logging → Enable debug logging, then on the Kodi machine:
grep "FCast Receiver:" ~/.kodi/temp/kodi.log
On LibreELEC and CoreELEC the log lives at /storage/.kodi/temp/kodi.log.
Troubleshooting
The Kodi box does not appear in my sender's device list
Discovery is done over mDNS, through Avahi, so the receiver only advertises itself on Linux
hosts — LibreELEC, CoreELEC, Raspbian, Debian and friends. On Windows, macOS and Android the
receiver works, but senders have to be pointed at it by IP address and port
46899.
On Linux, check that the sender and the Kodi box are on the same network segment — many routers keep a guest network, or a wireless band with client isolation, away from the rest of the LAN. From another machine on the network:
avahi-browse -rt _fcast._tcpIf the service is not listed there, the log lines from Reading the log say which discovery backend was tried and why it failed.
Audio drifts out of sync during long playback
After a long pause, or roughly forty minutes in, the audio can begin skipping seconds while
the video speeds up to catch it. This is an inputstream.adaptive problem rather
than a receiver one: it reproduces with any add-on playing adaptive streams, whether or not
FCast is involved (xbmc/xbmc#22625).
There is no workaround available from this add-on.
A CastLab photo album does not advance by itself
CastLab keeps its queue on the phone and sends one photo at a time, so each arrives as a single cast rather than as a playlist. Picture duration does not apply to those, by design: a photo cast on its own stays up until something dismisses it. Use CastLab's own autoplay, or a sender that sends a real playlist.
I cannot reach the Kodi menus while a photo is on screen
Kodi's picture viewer is a modal dialog and draws above everything, Settings included, so nothing else is reachable while a photo is up. This is Kodi's own behaviour — the official FCast receiver behaves the same way. Stop the cast from the sender, or close the picture from Kodi, and the interface comes back.
Playback speed from the sender does nothing
Turn on Settings → Player → Videos → Sync playback to display. Kodi supports speeds between 0.8× and 1.5×; anything a sender asks for outside that range is clamped to the nearest end rather than rejected.
Something else? Open an issue on GitHub, with the version you are running and the log lines from Reading the log.