Add M3U Radio music provider by cladkins · Pull Request #4180 · music-assistant/server

cladkins · 2026-06-11T21:40:58Z

What does this implement/fix?

Adds a new music provider, M3U Radio (m3uradio), which imports radio stations from a self-hosted M3U / IPTV playlist URL and exposes them as a native radio source: library sync, browse by group-title, and search.

Motivation: self-hosters maintain a station list in an M3U editor. Today the options are manually adding stations one by one via the builtin provider, or one-shot import scripts that go stale. This makes the playlist itself the source of truth.

Design notes:

Stable item IDs: tvg-id when present, otherwise a 16-char sha1 of name|url — favorites and history survive playlist refreshes.
Refresh: the playlist is re-fetched in a sync_library override on every scheduled library sync, so playlist edits flow in automatically.
Group filter: optional comma-separated group-title include-filter, for mixed TV/radio IPTV playlists. multi_instance: true allows several playlists.
Streaming: direct URL, StreamType.HTTP, no seeking (live radio). ICY metadata works out of the box.
No external dependencies — the parser is stdlib-only and covered by unit tests (tests/providers/m3uradio/), including the comma-inside-quoted-attributes edge case.

Tested locally against dev: library sync (441-station real-world playlist), browse, search, and end-to-end playback with ICY now-playing metadata.

Related issue (if applicable):

n/a

Types of changes

Checklist

The code change is tested and works locally.
pre-commit run --all-files passes.
pytest passes, and tests have been added/updated under tests/ where applicable.
For changes to shared models, the companion PR in music-assistant/models is linked. (n/a — no model changes)
For changes affecting the UI, the companion PR in music-assistant/frontend is linked. (n/a — no UI changes)
I have read and complied with the project's AI Policy for any AI-assisted contributions.
I have raised a PR against the documentation repository targeting the main or beta branch as appropriate. (docs PR to follow)

Generated with help from Claude Code

New music provider that imports radio stations from a self-hosted M3U / IPTV playlist and exposes them as a native radio source: library sync, browse by group-title, and search. - Stable item IDs: tvg-id when present, otherwise a 16-char sha1 of name|url, so favourites survive playlist refreshes. - Optional comma-separated group-title include-filter for mixed TV/radio IPTV playlists; multi_instance allows several playlists. - The playlist is re-fetched on every scheduled library sync so playlist edits are picked up automatically. - Direct-URL HTTP streaming, no seeking (live radio), no external pip requirements (stdlib-only parser). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions · 2026-06-11T21:42:15Z

🔒 Dependency Security Report

✅ No dependency changes detected in this PR.

cladkins · 2026-06-11T21:56:29Z

Closing while I review locally — will reopen when ready for review.

marcelveldt · 2026-06-12T21:23:49Z

+        return radio
+
+
+def parse_m3u(content: str) -> list[dict[str, str]]:


we have an existing m3u parser in helpers, maybe use that ? If it's missing some fields we could extend it

marcelveldt · 2026-06-12T21:25:31Z

+            raise MediaNotFoundError(f"Station {prov_radio_id} not found")
+        return self._parse_radio(st)
+
+    async def search(


do you really need search ? If all stations are imported to the library anyways, the library will already provide the search results.

Removed the search

Did you not yet push that change as I'm still seeing the search

I've been back up at work. I have not pushed the changes yet.

marcelveldt · 2026-06-17T21:42:46Z

+        ConfigEntry(
+            key=CONF_M3U_URL,
+            type=ConfigEntryType.STRING,
+            label="M3U / IPTV playlist URL",


we recently migrated the backend to support localization (which was added right after your pr got opened). Can you adjust these hardcoded strings to translation_key and a strings.json in your provider folder ?

Look at some of the other providers how this is done.

OzGav · 2026-06-19T00:05:21Z

Marking this as draft so we know what needs attention. Please press the Ready for Review button when it is ready again.

OzGav · 2026-06-19T00:16:11Z

+    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-") or "ungrouped"
+
+
+def _guess_content_type(url: str) -> ContentType:


ContentType.try_parse() is in the models already? More importantly, the established convention for live radio is to not guess, somafm sets content_type=ContentType.UNKNOWN and lets the stream be probed. You should drop the helper and its test and use ContentType.UNKNOWN (matching somafm) or ContentType.try_parse(st["url"])

OzGav · 2026-06-19T00:24:21Z

You don't override the base class is_streaming_provider property therefore it is set as TRUE

The practical effect is in the base sync_library deletion path with False, a station removed from the playlist gets fully removed from the library on the next sync but with True, it lingers as an orphaned in_library=False mapping.

What is your intent?

OzGav · 2026-06-19T00:28:31Z

+        groups_raw = self.config.get_value(CONF_GROUPS) or ""
+        group_filter = {g.strip().lower() for g in str(groups_raw).split(",") if g.strip()}
+        try:
+            async with self.mass.http_session.get(str(url)) as resp:


You should set a timeout value here

OzGav · 2026-06-19T00:37:54Z

+        try:
+            async with self.mass.http_session.get(str(url)) as resp:
+                resp.raise_for_status()
+                content = await resp.text()


This could raise an uncaught error. You could widen the caught errors below, but elsewhere in the codebase detect_charset is used to handle missing/wrong server charsets so read the raw bytes and decode with errors="replace" so it can't throw (see fetch_playlist in helpers/playlists.py).

github-actions Bot added the new-provider label Jun 11, 2026

cladkins closed this Jun 11, 2026

Merge remote-tracking branch 'origin/dev' into add-m3uradio-provider

b636854

cladkins reopened this Jun 12, 2026

Merge branch 'dev' into add-m3uradio-provider

5c386de

cladkins mentioned this pull request Jun 12, 2026

Add M3U Radio music provider documentation music-assistant/music-assistant.io#723

Open

cladkins marked this pull request as ready for review June 12, 2026 14:50

marcelveldt reviewed Jun 12, 2026

View reviewed changes

Comment thread music_assistant/providers/m3uradio/__init__.py

marcelveldt reviewed Jun 12, 2026

View reviewed changes

Merge branch 'dev' into add-m3uradio-provider

4ebf7d5

marcelveldt reviewed Jun 17, 2026

View reviewed changes

marcelveldt mentioned this pull request Jun 17, 2026

Guard against hardcoded ConfigEntry strings #4304

Merged

13 tasks

OzGav marked this pull request as draft June 19, 2026 00:05

OzGav reviewed Jun 19, 2026

View reviewed changes

		return radio


		def parse_m3u(content: str) -> list[dict[str, str]]:

		return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-") or "ungrouped"


		def _guess_content_type(url: str) -> ContentType:

Uh oh!

Conversation

cladkins commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this implement/fix?

Types of changes

Checklist

Uh oh!

github-actions Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔒 Dependency Security Report

Uh oh!

cladkins commented Jun 11, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

OzGav commented Jun 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

OzGav commented Jun 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cladkins commented Jun 11, 2026 •

edited

Loading

github-actions Bot commented Jun 11, 2026 •

edited

Loading