# MiracleCast: Wi-Fi Display (Miracast) for Linux as a Sink

> MiracleCast implements the Wi-Fi Display (Miracast) specification on Linux, allowing other devices to stream their screens to a Linux machine acting as a wireless display. The Display-Source side, which would stream from Linux to an external display, is documented in the README as not yet implemented.

**albfan/miraclecast** — Connect external monitors to your system via Wifi-Display specification also known as Miracast

- Repository: https://github.com/albfan/miraclecast
- Stars: 4,340 · Forks: 434
- Language: C
- License: NOASSERTION
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/albfan-miraclecast

## Sink vs. Source: Only One Side Is Implemented

The Wi-Fi Display specification defines two roles. A Display-Source streams local content to a remote display. A Display-Sink receives a stream and shows it. MiracleCast implements both roles in principle, but the README is explicit about what actually works: the Display-Source side, which would let a Linux system stream to an external Miracast screen, is described as "not implemented yet," with a reference to issue #4 in the repository for tracking.

What does work is the Display-Sink side. This allows a Linux machine to become a wireless display that other Miracast-capable devices can connect to and mirror their screens onto. The use case is running Linux on a device you want to use as a second screen for a phone, tablet, or another computer.

The README acknowledges the Display-Source limitation directly: "A lot of effort is put into making this as easy as connecting external displays via HDMI. Note: This is not implemented yet." Anyone who installs MiracleCast expecting to mirror a Linux desktop to a smart TV or wireless display adapter will be disappointed.

## Architecture: systemd, GStreamer, and wpa_supplicant

MiracleCast depends on four pieces of system infrastructure working together. systemd provides device management through udev, D-Bus communication through sd-bus, and service management. The minimum supported version is systemd 213; systemd 221 or later is recommended because earlier versions require a kdbus-enabled build.

glib is used for the current DHCP implementation. The README notes that this dependency will be removed once sd-dns gains DHCP-server capabilities, which indicates glib is a transitional dependency.

GStreamer handles the rendering of the received video stream. The repository includes a test script at res/test-viewer.sh to verify that all required GStreamer elements are installed. wpa_supplicant is spawned by MiracleCast with a custom configuration to manage the Wi-Fi P2P (Wi-Fi Direct) peer connection.

The hardware requirement is strict: the system needs a Wi-Fi adapter that supports Wi-Fi P2P (formerly Wi-Fi Direct). Not all adapters support this, even common ones. The README includes a test script at res/test-hardware-capabilities.sh to verify compatibility before attempting to build and run the software.

## Building and Installing MiracleCast on Linux

MiracleCast supports three build systems: autotools, cmake, and meson. The README links to a wiki page on building for detailed steps. Before building, confirm the systemd version is adequate:

```
$ systemctl --version
```

On Arch Linux, an AUR package is available (miraclecast-git). Arch users who are on a systemd version below 221 need to set the kdbus flag for the systemd-git dependency:

```
$ export _systemd_git_kdbus=--enable-kdbus
```

After building, the D-Bus policy file at res/org.freedesktop.miracle.conf must be copied to /etc/dbus-1/system.d/ to allow the daemon to communicate over the system bus.

For automatic interface selection using udev, the README describes a udev rule generated by res/write-udev-rule.sh, followed by configuring with:

```
$ ../configure --enable-rely-udev
```

Alternatively, the interface can be specified at runtime using the --interface option for miracle-wifid.

## Running MiracleCast as a Sink: Step by Step

Using MiracleCast as a sink requires stopping NetworkManager and wpa_supplicant first, since MiracleCast manages its own Wi-Fi stack for the P2P connection:

```
$ systemctl stop NetworkManager.service
$ systemctl stop wpa_supplicant.service
```

With those services stopped, launch the Wi-Fi daemon:

```
$ sudo miracle-wifid &
```

Then start the sink controller. When a network interface is detected (here, interface number 3), it will be listed:

```
$ sudo miracle-sinkctl
[ADD]  Link: 3
```

Inside the sinkctl interactive shell, run Wi-Fi Display on the detected link:

```
> run 3
```

At this point, MiracleCast advertises the Linux machine as a Miracast sink. The source device (phone, laptop, or other Miracast-capable device) can then discover and connect to it for screen mirroring.

The UIBC feature, which forwards mouse and keyboard events from the sink back to the source, is enabled by adding --uibc to the miracle-sinkctl startup command. The README states that single mouse events and key events are implemented.

The README also documents a peer-control workflow using miracle-wifictl instead of miracle-sinkctl. After stopping NetworkManager and launching miracle-wifid, running miracle-wifictl opens an alternative interactive shell. Enabling visibility and running the p2p-scan command discovers nearby P2P devices. The peer subcommand shows information about a specific device by its MAC address. The README notes that beyond scanning and listing, the practical use of this peer workflow is limited in its current state, and refers to issue #4 for progress on the peer-connection side.

## Limitations and Known Gaps

The most significant limitation is the unimplemented Display-Source side. That feature has been tracked in issue #4 since the project's early days and remains open.

The dependency on systemd is a hard requirement that limits MiracleCast to systemd-based Linux distributions. Systems running OpenRC, runit, or other init systems cannot use it without significant modification. Even on supported distributions, the minimum systemd version (213) excludes some older LTS releases, and the complexity around kdbus and pre-221 systemd versions adds fragility to the build process.

Stopping NetworkManager and wpa_supplicant to run MiracleCast means the Linux machine loses its normal network connectivity during a MiracleCast session. This is a significant operational cost for a development workstation or a server that needs to remain connected.

Autocompletion support exists (res/miraclecast-completion), but must be sourced manually. There is no packaged integration with bash-completion or zsh completion frameworks.

## GNOME Network Displays as an Alternative

GNOME Network Displays is a GTK application that implements wireless display protocols on Linux, including Miracast (Wi-Fi Display) and Chromecast. Unlike MiracleCast, it provides a graphical user interface and is maintained under the GNOME project umbrella. It targets the Display-Source role: casting from a Linux desktop to a wireless display, which is the use case MiracleCast explicitly does not support.

For the sink role (using Linux as a receiving display), MiracleCast remains one of the few Linux implementations. GNOME Network Displays focuses on the source side. The two projects therefore serve complementary, not competing, use cases despite sharing the Miracast protocol.

MiracleCast is licensed under the GNU LGPL. The last push to the repository was on 2026-03-10, and the repository has no official GitHub releases. Teams building production workflows around wireless display on Linux should evaluate whether the sink-only functionality and the maintenance situation fit their requirements before committing to MiracleCast.

## Conclusion

MiracleCast is the right tool for a Linux developer who wants to receive a Miracast stream from an Android, Windows, or other Wi-Fi Display compatible device onto a Linux machine, and who is comfortable resolving systemd version requirements and wpa_supplicant configuration by hand. It is the wrong choice for anyone who wants to broadcast from Linux to an external Miracast screen: the README states that use case is not implemented. The last push to the repository was on 2026-03-10, and the project has no releases, so teams that need a supported path should evaluate GNOME Network Displays first.

## FAQ

### Is MiracleCast available on Linux?

Yes, MiracleCast is a Linux-only implementation of the Wi-Fi Display (Miracast) specification. It requires systemd, GStreamer, wpa_supplicant, and a Wi-Fi adapter with P2P support. It supports autotools, cmake, and meson builds, and an AUR package exists for Arch Linux.

### How to use MiracleCast

MiracleCast is used primarily as a sink: stop NetworkManager and wpa_supplicant, run miracle-wifid in the background, then run miracle-sinkctl. Inside sinkctl, issue the run command with the detected link number to advertise the Linux machine as a Miracast display. The README documents this step by step.

### MiracleCast vs GNOME Network Displays

MiracleCast implements the sink side of Miracast (receiving a stream onto a Linux machine) while GNOME Network Displays focuses on the source side (casting from a Linux desktop to a wireless screen). The Display-Source side of MiracleCast is documented in the README as not yet implemented, making the two projects largely complementary rather than direct alternatives.

## Sources

- [albfan/miraclecast on GitHub](https://github.com/albfan/miraclecast)
- [Issues](https://github.com/albfan/miraclecast/issues)
- [README](https://github.com/albfan/miraclecast/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/albfan-miraclecast