https://github.com/aminekun90/mdns_listener_advanced
Simple mDNS Listener to publish and listen .local hostnames in your network compatible with zeroconf, bonjour, avahi you can also scan any mdns device present in the network
https://github.com/aminekun90/mdns_listener_advanced
avahi mdns multicast-dns zeroconf
Last synced: about 2 months ago
JSON representation
Simple mDNS Listener to publish and listen .local hostnames in your network compatible with zeroconf, bonjour, avahi you can also scan any mdns device present in the network
- Host: GitHub
- URL: https://github.com/aminekun90/mdns_listener_advanced
- Owner: aminekun90
- License: mit
- Created: 2018-08-31T12:16:51.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2026-02-23T14:25:04.000Z (3 months ago)
- Last Synced: 2026-02-23T22:24:59.402Z (3 months ago)
- Topics: avahi, mdns, multicast-dns, zeroconf
- Language: TypeScript
- Homepage:
- Size: 2.06 MB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- Contributing: Contributing.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Audit: audit-security.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# mDNS Listener Advanced
[](https://github.com/aminekun90/mdns_listener_advanced/graphs/commit-activity) [](https://github.com/aminekun90/mdns_listener_advanced/releases) [](https://github.com/aminekun90/mdns_listener_advanced/actions) [](https://github.com/aminekun90/mdns_listener_advanced/blob/master/LICENSE) [](https://socket.dev/npm/package/mdns-listener-advanced) [](https://www.npmjs.com/package/mdns-listener-advanced)
> **🚀 Major Update v3.4.0+**: This package has been re-architected to be **Zero-Dependency**. It now uses native Node.js modules (`dgram`, `crypto`) for maximum performance, security, and compatibility. No more heavy dependencies like `bonjour-service` or `multicast-dns`.
**mDNS Listener Advanced** is a robust, cross-platform Node.js library for Multicast DNS (mDNS) operations. It allows you to:
1. **Listen** for specific `.local` hostnames.
2. **Publish** your own device/service to the network.
3. **Scan/Discover** all devices and services on the network (Service Discovery).
Compatible with mdns, Avahi, Bonjour, and Zeroconf.
## Requirements
- **Node.js:** v22 or later (Recommended).
- **OS:** Fully tested on Windows 11, Ubuntu 20.04+, and macOS (Sonoma/Sequoia/Tahoe).
- Not tested on Docker containers.
- This library need to access the local network to work properly.
## Installation
```bash
npm install mdns-listener-advanced
# or preferred way
yarn add mdns-listener-advanced
```
## Features
- 📦 Zero Dependencies: Lightweight and secure.
- 🔍 Targeted Listening: Detect specific devices by name (e.g., MyDevice.local).
- 📡 Service Discovery: Scan the network for all services (e.g., Google Cast, Printers).
- 📢 Native Publisher: Announce your presence without external tools.
- 🛡️ TypeScript: Written in TypeScript with full type definitions included.
## Usage Examples
### 1. Basic Listener (JavaScript)
Listen for specific devices defined in your constructor or hosts file.
```javascript
import Core, { EmittedEvent } from "mdns-listener-advanced";
// Look for a device named "MyDevice2"
const mdns = new Core(["MyDevice2"], null, {
debug: false
});
const event = mdns.listen();
// 1. Handle targeted response
event.on(EmittedEvent.RESPONSE, (found_hostnames) => {
console.log("✅ Found Target:", found_hostnames);
// mdns.stop(); // Stop listening if needed
});
// 2. Handle errors
event.on(EmittedEvent.ERROR, (error) => {
console.error("❌ Error:", error);
});
```
### 2. Service Discovery / Scanning (TypeScript)
New in v3.4.0: actively query the network to find devices (Printers, Chromecast, HomeKit, etc.).
```typescript
import { Core, EmittedEvent, Device } from 'mdns-listener-advanced';
// or import Core,{ EmittedEvent, Device } from 'mdns-listener-advanced';
const mdns = new Core();
const event = mdns.listen();
event.on(EmittedEvent.DISCOVERY, (device: Device) => {
console.log(`🔎 Discovered [${device.type}]:`, device.name, device.data);
});
// Scan for Google Cast devices
mdns.scan("_googlecast._tcp.local");
// OR Scan for EVERYTHING
// mdns.scan("_services._dns-sd._udp.local");
```
### 3. Publishing a Host
Announce your service to the network.
```javascript
import { Core } from "mdns-listener-advanced";
// or import Core,{ EmittedEvent, Device } from 'mdns-listener-advanced';
const mdns = new Core();
// Publish "MyCoolService.local"
const customData = { hello: "world" };
mdns.publish("MyCoolService",customData, 30000); // 30000 ms = 30 seconds by default
// Your device is now visible to other mDNS scanners!
// // 2. Start Listener
const event = mdns.listen();
// // --- HANDLERS ---
event.on(EmittedEvent.RESPONSE, (found_hostnames: Device[]) => {
mdns.info("✅ Found TARGETED Host:", found_hostnames);
});
// stop
```
output:
```shell
[MDNS ADVANCED] INFO: ✅ Found TARGETED Host: [
{
name: 'MyDevice2',
type: 'TXT',
data: {
uuid: '"eec91263-de12-4525-ba08-81adad17-ceb3"',
ipv4: '"192.168.1.102"',
hello: 'world'
}
}
]
```
### 4. Run the provided example
Clone the repository and run the following command:
```bash
# optional install (no dependencies required to run the example)
# yarn install
yarn start
```
## API Documentation
Class: `Core`
### Constructor
```typescript
// All args are optional
new Core(hostsList, mdnsHostsPath, options, logger)
```
| Parameter | Type | Description |
|---------------|----------|-------------------------------------------------------------------------------------------|
| hostsList | string[] | Optional array of hostnames to listen for (e.g. ['device1']). |
| mdnsHostsPath | string | Optional absolute path to a custom hosts file. |
| options | Options | "Config object: { debug: boolean, disableListener: boolean, disablePublisher: boolean }." |
| logger | any | "Custom logger instance (must have .info, .debug, .warn, .error)." |
### Methods
| Method | Description |
|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| listen(ref) | Starts the UDP socket and joins the Multicast group. Returns the EventEmitter, you can provide a string to listen for a specific host check example.ts. |
| publish(name,data, interval) | "Broadcasts an mDNS response, announcing name.local with your IP address. add data to the TXT record, personalize the interval by default set to 30000ms." |
| scan(serviceType) | (New) Sends a query to the network. Default serviceType is _services._dns-sd._udp.local. |
| stop() | Closes the socket and removes all event listeners. |
### Events (EmittedEvent)
| Event Name | Enum | Payload Type | Description |
|--------------------|---------------------------|--------------|----------------------------------------------------------------|
| """response""" | EmittedEvent.RESPONSE | Device[] | Fired when a Targeted Host (from your list) is found. |
| """discovery""" | EmittedEvent.DISCOVERY | Device | "Fired when scan() finds ANY device (PTR, SRV, or A records)." |
| """raw_response""" | EmittedEvent.RAW_RESPONSE | object | The full raw packet structure (advanced debugging). |
| """error""" | EmittedEvent.ERROR | Error | Fired on socket errors or configuration issues. |
---
### Configuration Files
You can optionally use a file to manage the list of devices you want to detect (Targeted Listening).
Location:
- Windows: `C:\Users\\.mdns-hosts`
- Linux/macOS: `~/.mdns-hosts`
```plaintext
LivingRoomTV
OfficePrinter
RaspberryPi
```
If you do not provide a constructor list or this file, the listener will warn you but still function (useful if you only want to use scan() or publish())
---
### Troubleshooting
- Firewall: mDNS uses UDP port 5353. Ensure your firewall allows traffic on this port.
- Docker: If running in Docker, you must use network_mode: "host" so the container can receive Multicast packets from the physical network.
- Windows: You might need to allow Node.js through the Windows Defender Firewall on the first run.
- macOS + Docker limitations : running docker in host mode might not work on macOS, since the container is not able to access the host network.
## Support & Contribution
Issues: [Open an issue here](https://github.com/aminekun90/mdns_listener_advanced/issues)
Contact: [Connect on LinkedIn](https://www.linkedin.com/in/amine-bouzahar/)
### If you appreciate mdns-listener-advanced, consider supporting the project. :coffee:
I dedicate time and effort on writing and maintaining this library since 2017 and I'm grateful for your support.
If this library saved you time, consider Donating!
[](https://www.paypal.com/paypalme/aminebouzahar)
---
Original Credit: Based on concepts from @Richie765, now fully rewritten for modern Node.js and TypeScript.