PyDLNA 0.1.4__py3-none-any.whl

pydlna/formatters.py

@@ -0,0 +1,325 @@
+"""XML builders and parsers for every UPnP/DLNA document PyDLNA speaks.
+
+Everything on the wire (SSDP aside) is XML: the device description, the
+service descriptions (SCPD), the SOAP envelopes used for actions, and the
+DIDL-Lite metadata describing media. Keeping all of it in one place makes
+the wire format easy to audit.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Mapping, Optional
+from xml.etree import ElementTree as ET
+from xml.sax.saxutils import escape
+
+from pydlna.errors import UPnPError
+from pydlna.file import MediaFile, MediaItem
+
+SOAP_NS = "http://schemas.xmlsoap.org/soap/envelope/"
+
+_DIDL_OPEN = (
+    '<DIDL-Lite xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/" '
+    'xmlns:dc="http://purl.org/dc/elements/1.1/" '
+    'xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/" '
+    'xmlns:dlna="urn:schemas-dlna-org:metadata-1-0/">'
+)
+
+# SCPD tables: (action, [(argument, direction, related state variable), ...])
+_CONTENT_DIRECTORY_ACTIONS = [
+    ("GetSearchCapabilities", [("SearchCaps", "out", "SearchCapabilities")]),
+    ("GetSortCapabilities", [("SortCaps", "out", "SortCapabilities")]),
+    ("GetSystemUpdateID", [("Id", "out", "SystemUpdateID")]),
+    ("Browse", [
+        ("ObjectID", "in", "A_ARG_TYPE_ObjectID"),
+        ("BrowseFlag", "in", "A_ARG_TYPE_BrowseFlag"),
+        ("Filter", "in", "A_ARG_TYPE_Filter"),
+        ("StartingIndex", "in", "A_ARG_TYPE_Index"),
+        ("RequestedCount", "in", "A_ARG_TYPE_Count"),
+        ("SortCriteria", "in", "A_ARG_TYPE_SortCriteria"),
+        ("Result", "out", "A_ARG_TYPE_Result"),
+        ("NumberReturned", "out", "A_ARG_TYPE_Count"),
+        ("TotalMatches", "out", "A_ARG_TYPE_Count"),
+        ("UpdateID", "out", "A_ARG_TYPE_UpdateID"),
+    ]),
+    ("Search", [
+        ("ContainerID", "in", "A_ARG_TYPE_ObjectID"),
+        ("SearchCriteria", "in", "A_ARG_TYPE_SearchCriteria"),
+        ("Filter", "in", "A_ARG_TYPE_Filter"),
+        ("StartingIndex", "in", "A_ARG_TYPE_Index"),
+        ("RequestedCount", "in", "A_ARG_TYPE_Count"),
+        ("SortCriteria", "in", "A_ARG_TYPE_SortCriteria"),
+        ("Result", "out", "A_ARG_TYPE_Result"),
+        ("NumberReturned", "out", "A_ARG_TYPE_Count"),
+        ("TotalMatches", "out", "A_ARG_TYPE_Count"),
+        ("UpdateID", "out", "A_ARG_TYPE_UpdateID"),
+    ]),
+]
+
+# SCPD state variables: (name, data type, sends events, allowed values)
+_CONTENT_DIRECTORY_VARIABLES = [
+    ("A_ARG_TYPE_ObjectID", "string", False, None),
+    ("A_ARG_TYPE_Result", "string", False, None),
+    ("A_ARG_TYPE_SearchCriteria", "string", False, None),
+    ("A_ARG_TYPE_BrowseFlag", "string", False, ["BrowseMetadata", "BrowseDirectChildren"]),
+    ("A_ARG_TYPE_Filter", "string", False, None),
+    ("A_ARG_TYPE_SortCriteria", "string", False, None),
+    ("A_ARG_TYPE_Index", "ui4", False, None),
+    ("A_ARG_TYPE_Count", "ui4", False, None),
+    ("A_ARG_TYPE_UpdateID", "ui4", False, None),
+    ("SearchCapabilities", "string", False, None),
+    ("SortCapabilities", "string", False, None),
+    ("SystemUpdateID", "ui4", True, None),
+]
+
+_CONNECTION_MANAGER_ACTIONS = [
+    ("GetProtocolInfo", [
+        ("Source", "out", "SourceProtocolInfo"),
+        ("Sink", "out", "SinkProtocolInfo"),
+    ]),
+    ("GetCurrentConnectionIDs", [("ConnectionIDs", "out", "CurrentConnectionIDs")]),
+    ("GetCurrentConnectionInfo", [
+        ("ConnectionID", "in", "A_ARG_TYPE_ConnectionID"),
+        ("RcsID", "out", "A_ARG_TYPE_RcsID"),
+        ("AVTransportID", "out", "A_ARG_TYPE_AVTransportID"),
+        ("ProtocolInfo", "out", "A_ARG_TYPE_ProtocolInfo"),
+        ("PeerConnectionManager", "out", "A_ARG_TYPE_ConnectionManager"),
+        ("PeerConnectionID", "out", "A_ARG_TYPE_ConnectionID"),
+        ("Direction", "out", "A_ARG_TYPE_Direction"),
+        ("Status", "out", "A_ARG_TYPE_ConnectionStatus"),
+    ]),
+]
+
+_CONNECTION_MANAGER_VARIABLES = [
+    ("SourceProtocolInfo", "string", True, None),
+    ("SinkProtocolInfo", "string", True, None),
+    ("CurrentConnectionIDs", "string", True, None),
+    ("A_ARG_TYPE_ConnectionStatus", "string", False,
+     ["OK", "ContentFormatMismatch", "InsufficientBandwidth", "UnreliableChannel"]),
+    ("A_ARG_TYPE_ConnectionManager", "string", False, None),
+    ("A_ARG_TYPE_Direction", "string", False, ["Input", "Output"]),
+    ("A_ARG_TYPE_ProtocolInfo", "string", False, None),
+    ("A_ARG_TYPE_ConnectionID", "i4", False, None),
+    ("A_ARG_TYPE_AVTransportID", "i4", False, None),
+    ("A_ARG_TYPE_RcsID", "i4", False, None),
+]
+
+
+class XMLFormatter:
+    """Builds and parses every XML document PyDLNA speaks."""
+
+    # -- Device & service descriptions -----------------------------------
+
+    @staticmethod
+    def device_description(udn: str, friendly_name: str) -> str:
+        services = "".join(
+            "<service>"
+            f"<serviceType>urn:schemas-upnp-org:service:{name}:1</serviceType>"
+            f"<serviceId>urn:upnp-org:serviceId:{name}</serviceId>"
+            f"<SCPDURL>/scpd/{name}.xml</SCPDURL>"
+            f"<controlURL>/control/{name}</controlURL>"
+            f"<eventSubURL>/events/{name}</eventSubURL>"
+            "</service>"
+            for name in ("ContentDirectory", "ConnectionManager")
+        )
+        return (
+            '<?xml version="1.0" encoding="utf-8"?>'
+            '<root xmlns="urn:schemas-upnp-org:device-1-0">'
+            "<specVersion><major>1</major><minor>0</minor></specVersion>"
+            "<device>"
+            "<deviceType>urn:schemas-upnp-org:device:MediaServer:1</deviceType>"
+            f"<friendlyName>{escape(friendly_name)}</friendlyName>"
+            "<manufacturer>PyDLNA</manufacturer>"
+            "<modelName>PyDLNA Media Server</modelName>"
+            "<modelNumber>0.1</modelNumber>"
+            f"<UDN>{escape(udn)}</UDN>"
+            '<dlna:X_DLNADOC xmlns:dlna="urn:schemas-dlna-org:device-1-0">DMS-1.50</dlna:X_DLNADOC>'
+            f"<serviceList>{services}</serviceList>"
+            "</device></root>"
+        )
+
+    @staticmethod
+    def scpd_content_directory() -> str:
+        return XMLFormatter._scpd(_CONTENT_DIRECTORY_ACTIONS, _CONTENT_DIRECTORY_VARIABLES)
+
+    @staticmethod
+    def scpd_connection_manager() -> str:
+        return XMLFormatter._scpd(_CONNECTION_MANAGER_ACTIONS, _CONNECTION_MANAGER_VARIABLES)
+
+    @staticmethod
+    def _scpd(actions: list, variables: list) -> str:
+        action_xml = "".join(
+            "<action>"
+            f"<name>{name}</name>"
+            "<argumentList>"
+            + "".join(
+                f"<argument><name>{arg}</name><direction>{direction}</direction>"
+                f"<relatedStateVariable>{related}</relatedStateVariable></argument>"
+                for arg, direction, related in arguments
+            )
+            + "</argumentList></action>"
+            for name, arguments in actions
+        )
+        variable_xml = "".join(
+            f'<stateVariable sendEvents="{"yes" if events else "no"}">'
+            f"<name>{name}</name><dataType>{data_type}</dataType>"
+            + (
+                "<allowedValueList>"
+                + "".join(f"<allowedValue>{value}</allowedValue>" for value in allowed)
+                + "</allowedValueList>"
+                if allowed
+                else ""
+            )
+            + "</stateVariable>"
+            for name, data_type, events, allowed in variables
+        )
+        return (
+            '<?xml version="1.0" encoding="utf-8"?>'
+            '<scpd xmlns="urn:schemas-upnp-org:service-1-0">'
+            "<specVersion><major>1</major><minor>0</minor></specVersion>"
+            f"<actionList>{action_xml}</actionList>"
+            f"<serviceStateTable>{variable_xml}</serviceStateTable>"
+            "</scpd>"
+        )
+
+    # -- SOAP envelopes ----------------------------------------------------
+
+    @staticmethod
+    def soap_envelope(action: str, service_type: str, args: Mapping[str, object]) -> str:
+        args_xml = "".join(
+            f"<{key}>{escape(str(value))}</{key}>" for key, value in args.items()
+        )
+        return (
+            '<?xml version="1.0" encoding="utf-8"?>'
+            f'<s:Envelope xmlns:s="{SOAP_NS}" '
+            's:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">'
+            f'<s:Body><u:{action} xmlns:u="{service_type}">{args_xml}</u:{action}></s:Body>'
+            "</s:Envelope>"
+        )
+
+    @staticmethod
+    def soap_response(action: str, service_type: str, fields: Mapping[str, str]) -> str:
+        return XMLFormatter.soap_envelope(f"{action}Response", service_type, fields)
+
+    @staticmethod
+    def soap_fault(code: int, description: str) -> str:
+        return (
+            '<?xml version="1.0" encoding="utf-8"?>'
+            f'<s:Envelope xmlns:s="{SOAP_NS}" '
+            's:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">'
+            "<s:Body><s:Fault>"
+            "<faultcode>s:Client</faultcode><faultstring>UPnPError</faultstring>"
+            '<detail><UPnPError xmlns="urn:schemas-upnp-org:control-1-0">'
+            f"<errorCode>{code}</errorCode>"
+            f"<errorDescription>{escape(description)}</errorDescription>"
+            "</UPnPError></detail>"
+            "</s:Fault></s:Body></s:Envelope>"
+        )
+
+    @staticmethod
+    def parse_soap_action(body: bytes) -> tuple[str, dict[str, str]]:
+        """Extract ``(action, arguments)`` from an incoming SOAP request."""
+        element = _body_child(ET.fromstring(body))
+        if element is None:
+            raise ValueError("SOAP body is empty")
+        return _local_name(element.tag), {
+            _local_name(child.tag): (child.text or "") for child in element
+        }
+
+    @staticmethod
+    def parse_soap_response(body: bytes, action: str) -> dict[str, str]:
+        """Parse a SOAP response body into a dict; raise on SOAP faults."""
+        element = _body_child(ET.fromstring(body))
+        if element is None:
+            raise ValueError("SOAP body is empty")
+        if _local_name(element.tag) == "Fault":
+            code, description = XMLFormatter.parse_soap_fault(body)
+            raise UPnPError(code, description)
+        return {_local_name(child.tag): (child.text or "") for child in element}
+
+    @staticmethod
+    def parse_soap_fault(body: bytes) -> tuple[int, str]:
+        code, description = 0, "Unknown UPnP error"
+        for element in ET.fromstring(body).iter():
+            name = _local_name(element.tag)
+            if name == "errorCode":
+                try:
+                    code = int(element.text or 0)
+                except ValueError:
+                    pass
+            elif name == "errorDescription":
+                description = element.text or description
+        return code, description
+
+    # -- DIDL-Lite -----------------------------------------------------------
+
+    @staticmethod
+    def didl_root_container(title: str, child_count: int) -> str:
+        return (
+            _DIDL_OPEN
+            + f'<container id="0" parentID="-1" childCount="{child_count}" '
+            'restricted="1" searchable="1">'
+            f"<dc:title>{escape(title)}</dc:title>"
+            "<upnp:class>object.container.storageFolder</upnp:class>"
+            "</container></DIDL-Lite>"
+        )
+
+    @staticmethod
+    def didl_items(files: Iterable[MediaFile], base_url: str) -> str:
+        items = []
+        for media in files:
+            url = f"{base_url}/media/{media.id}"
+            items.append(
+                f'<item id="{escape(media.id)}" parentID="0" restricted="1">'
+                f"<dc:title>{escape(media.title or '')}</dc:title>"
+                f"<upnp:class>{media.upnp_class}</upnp:class>"
+                f'<res protocolInfo="{escape(media.protocol_info)}" '
+                f'size="{media.size}">{escape(url)}</res>'
+                "</item>"
+            )
+        return _DIDL_OPEN + "".join(items) + "</DIDL-Lite>"
+
+    @staticmethod
+    def parse_didl_lite(xml_text: str) -> list[MediaItem]:
+        """Parse a DIDL-Lite document (e.g. a Browse result) into media items."""
+        if not xml_text.strip():
+            return []
+        items = []
+        for element in ET.fromstring(xml_text):
+            kind = _local_name(element.tag)
+            if kind not in ("item", "container"):
+                continue
+            entry = MediaItem(
+                id=element.get("id", ""),
+                parent_id=element.get("parentID", "0"),
+                is_container=(kind == "container"),
+            )
+            for child in element:
+                name = _local_name(child.tag)
+                if name == "title":
+                    entry.title = child.text or ""
+                elif name == "class":
+                    entry.upnp_class = child.text or ""
+                elif name == "res":
+                    entry.url = (child.text or "").strip()
+                    parts = child.get("protocolInfo", "").split(":")
+                    if len(parts) >= 3:
+                        entry.mime_type = parts[2]
+                    try:
+                        entry.size = int(child.get("size") or 0)
+                    except ValueError:
+                        pass
+            items.append(entry)
+        return items
+
+
+def _local_name(tag: str) -> str:
+    """Strip the ``{namespace}`` prefix from an ElementTree tag."""
+    return tag.rsplit("}", 1)[-1]
+
+
+def _body_child(envelope: ET.Element) -> Optional[ET.Element]:
+    """The first element inside the SOAP ``Body`` of an envelope."""
+    for child in envelope:
+        if _local_name(child.tag) == "Body":
+            return next(iter(child), None)
+    return None

pydlna/handlers.py

@@ -0,0 +1,174 @@
+"""HTTP request handlers for the PyDLNA media server.
+
+One handler class routes everything a DLNA device can send:
+
+* ``GET``/``HEAD`` — device description, SCPD documents, and media bytes
+  with byte-range support (renderers rely on ranges for seeking),
+* ``POST`` — SOAP control actions, dispatched to the UPnP services,
+* ``SUBSCRIBE``/``UNSUBSCRIBE`` — GENA eventing stubs.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from http.server import BaseHTTPRequestHandler
+from urllib.parse import urlsplit
+from xml.etree.ElementTree import ParseError
+
+from pydlna.errors import UPnPError
+from pydlna.formatters import XMLFormatter
+
+logger = logging.getLogger(__name__)
+
+_CHUNK = 64 * 1024
+
+
+class DLNARequestHandler(BaseHTTPRequestHandler):
+    """Routes HTTP requests to the services and media of a ``DLNAServer``."""
+
+    server_version = "PyDLNA/0.1"
+    protocol_version = "HTTP/1.1"
+
+    @property
+    def app(self):
+        """The ``DLNAServer`` instance behind this request."""
+        return self.server.app  # type: ignore[attr-defined]
+
+    def log_message(self, fmt: str, *args: object) -> None:
+        logger.debug("%s - %s", self.address_string(), fmt % args)
+
+    # -- GET / HEAD ------------------------------------------------------
+
+    def do_GET(self) -> None:
+        self._route_get(send_body=True)
+
+    def do_HEAD(self) -> None:
+        self._route_get(send_body=False)
+
+    def _route_get(self, send_body: bool) -> None:
+        path = urlsplit(self.path).path
+        if path in ("/", "/device.xml"):
+            self._send_xml(self.app.device_description(), send_body=send_body)
+        elif path == "/scpd/ContentDirectory.xml":
+            self._send_xml(XMLFormatter.scpd_content_directory(), send_body=send_body)
+        elif path == "/scpd/ConnectionManager.xml":
+            self._send_xml(XMLFormatter.scpd_connection_manager(), send_body=send_body)
+        elif path.startswith("/media/"):
+            self._send_media(path.rsplit("/", 1)[-1], send_body)
+        else:
+            self.send_error(404, "Not Found")
+
+    # -- POST (SOAP control) ----------------------------------------------
+
+    _CONTROL_SERVICES = {
+        "/control/ContentDirectory": "content_directory",
+        "/control/ConnectionManager": "connection_manager",
+    }
+
+    def do_POST(self) -> None:
+        attribute = self._CONTROL_SERVICES.get(urlsplit(self.path).path)
+        if attribute is None:
+            self.send_error(404, "Not Found")
+            return
+        length = int(self.headers.get("Content-Length") or 0)
+        payload = self.rfile.read(length)
+        try:
+            action, args = XMLFormatter.parse_soap_action(payload)
+        except (ParseError, ValueError):
+            self.send_error(400, "Malformed SOAP request")
+            return
+        service = getattr(self.app, attribute)
+        try:
+            result = service.handle(action, args, base_url=self._request_base())
+        except UPnPError as exc:
+            self._send_xml(XMLFormatter.soap_fault(exc.code, exc.description), status=500)
+            return
+        self._send_xml(XMLFormatter.soap_response(action, service.service_type, result))
+
+    # -- SUBSCRIBE / UNSUBSCRIBE (GENA) -------------------------------------
+    # Eventing is stubbed: subscriptions are accepted so renderers stay
+    # happy, but no NOTIFY messages are sent (the library is static).
+
+    def do_SUBSCRIBE(self) -> None:
+        if "CALLBACK" not in self.headers and "SID" not in self.headers:
+            self.send_error(412, "Precondition Failed")
+            return
+        self.send_response(200)
+        self.send_header("SID", f"uuid:{uuid.uuid4()}")
+        self.send_header("TIMEOUT", "Second-1800")
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
+    def do_UNSUBSCRIBE(self) -> None:
+        self.send_response(200)
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
+    # -- Internals -----------------------------------------------------------
+
+    def _request_base(self) -> str:
+        host = self.headers.get("Host")
+        return f"http://{host}" if host else self.app.base_url
+
+    def _send_xml(self, text: str, status: int = 200, send_body: bool = True) -> None:
+        payload = text.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", 'text/xml; charset="utf-8"')
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        if send_body:
+            self.wfile.write(payload)
+
+    def _send_media(self, item_id: str, send_body: bool) -> None:
+        media = self.app.library.get(item_id)
+        if media is None:
+            self.send_error(404, "Not Found")
+            return
+        try:
+            size = media.path.stat().st_size
+        except OSError:
+            self.send_error(404, "Not Found")
+            return
+        start, end, status = self._resolve_range(size)
+        length = max(0, end - start + 1)
+        self.send_response(status)
+        self.send_header("Content-Type", media.mime_type or "application/octet-stream")
+        self.send_header("Content-Length", str(length))
+        self.send_header("Accept-Ranges", "bytes")
+        self.send_header("contentFeatures.dlna.org", "DLNA.ORG_OP=01;DLNA.ORG_CI=0")
+        self.send_header("transferMode.dlna.org", "Streaming")
+        if status == 206:
+            self.send_header("Content-Range", f"bytes {start}-{end}/{size}")
+        self.end_headers()
+        if not send_body:
+            return
+        try:
+            with media.path.open("rb") as stream:
+                stream.seek(start)
+                remaining = length
+                while remaining > 0:
+                    chunk = stream.read(min(_CHUNK, remaining))
+                    if not chunk:
+                        break
+                    self.wfile.write(chunk)
+                    remaining -= len(chunk)
+        except (BrokenPipeError, ConnectionResetError):
+            pass  # The renderer wandered off mid-stream; nothing to fix.
+
+    def _resolve_range(self, size: int) -> tuple[int, int, int]:
+        """Translate a ``Range`` header into ``(start, end, http_status)``."""
+        header = self.headers.get("Range", "")
+        if header.startswith("bytes="):
+            first, _, last = header[6:].split(",", 1)[0].partition("-")
+            try:
+                if first:
+                    start = int(first)
+                    end = min(int(last), size - 1) if last else size - 1
+                else:  # Suffix range: the last N bytes.
+                    start, end = max(0, size - int(last)), size - 1
+                if 0 <= start <= end:
+                    return start, end, 206
+            except ValueError:
+                pass
+        return 0, size - 1, 200

pydlna/server.py

@@ -0,0 +1,168 @@
+"""The PyDLNA media server: HTTP, UPnP services and SSDP glued together."""
+
+from __future__ import annotations
+
+import logging
+import mimetypes
+import socket
+import threading
+import uuid
+from http.server import ThreadingHTTPServer
+from pathlib import Path
+from typing import Iterator, Optional, Union
+
+from pydlna.discovery import SSDPResponder
+from pydlna.file import MediaFile
+from pydlna.formatters import XMLFormatter
+from pydlna.handlers import DLNARequestHandler
+from pydlna.services import ConnectionManagerService, ContentDirectoryService
+
+logger = logging.getLogger(__name__)
+
+_MEDIA_TOP_TYPES = ("audio", "video", "image")
+
+
+class MediaLibrary:
+    """A flat collection of media files, each with a stable DLNA object id."""
+
+    def __init__(self, server: Optional["DLNAServer"] = None) -> None:
+        self.server = server
+        self._items: dict[str, MediaFile] = {}
+
+    def add(self, path: Union[str, Path, MediaFile]) -> MediaFile:
+        """Add a single file and return it with its new object id."""
+        media = path if isinstance(path, MediaFile) else MediaFile(Path(path))
+        media.id = f"item-{len(self._items)}"
+        media.library = self
+        self._items[media.id] = media
+        return media
+
+    def add_directory(self, root: Union[str, Path], recursive: bool = True) -> int:
+        """Add every audio/video/image file under a directory; returns the count."""
+        root = Path(root).expanduser()
+        pattern = "**/*" if recursive else "*"
+        added = 0
+        for path in sorted(root.glob(pattern)):
+            if not path.is_file():
+                continue
+            mime_type = mimetypes.guess_type(path.name)[0] or ""
+            if mime_type.split("/", 1)[0] in _MEDIA_TOP_TYPES:
+                self.add(path)
+                added += 1
+        return added
+
+    def get(self, item_id: str) -> Optional[MediaFile]:
+        return self._items.get(item_id)
+
+    def __getitem__(self, index: int) -> MediaFile:
+        return self.files[index]
+
+    @property
+    def files(self) -> list[MediaFile]:
+        return list(self._items.values())
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __iter__(self) -> Iterator[MediaFile]:
+        return iter(self._items.values())
+
+
+class DLNAServer:
+    """A DLNA Digital Media Server.
+
+    Serves device/service descriptions and media bytes over HTTP, answers
+    SOAP actions on its UPnP services, and advertises itself over SSDP.
+    """
+
+    def __init__(self, name: str = "PyDLNA Media Server", host: str = "0.0.0.0",
+                 port: int = 8200, udn: Optional[str] = None) -> None:
+        self.name = name
+        self.host = host
+        self.port = port
+        self.udn = udn or f"uuid:{uuid.uuid4()}"
+        self.library = MediaLibrary(server=self)
+        self.content_directory = ContentDirectoryService(self.library, root_title=name)
+        self.connection_manager = ConnectionManagerService(self.library)
+        self._httpd: Optional[ThreadingHTTPServer] = None
+        self._ssdp: Optional[SSDPResponder] = None
+
+    def __enter__(self) -> "DLNAServer":
+        """Start the server; usable as ``with DLNAServer(...) as server:``."""
+        self.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.stop()
+
+    # -- Properties -----------------------------------------------------------
+
+    @property
+    def local_ip(self) -> str:
+        """Best-effort guess of the LAN IP to advertise."""
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        try:
+            sock.connect(("239.255.255.250", 1900))  # UDP: no traffic is sent
+            return sock.getsockname()[0]
+        except OSError:
+            return "127.0.0.1"
+        finally:
+            sock.close()
+
+    def local_ip_for(self, target: str) -> str:
+        """The local IP that traffic to ``target`` would leave from."""
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        try:
+            sock.connect((target, 80))  # UDP: no traffic is sent
+            return sock.getsockname()[0]
+        except OSError:
+            return self.local_ip
+        finally:
+            sock.close()
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{self.local_ip}:{self.port}"
+
+    # -- Descriptions ------------------------------------------------------------
+
+    def device_description(self) -> str:
+        return XMLFormatter.device_description(self.udn, self.name)
+
+    # -- Lifecycle ------------------------------------------------------------------
+
+    def start(self, advertise: bool = True) -> None:
+        """Start the HTTP server (and SSDP advertisements) in the background."""
+        if self._httpd is not None:
+            return
+        self._httpd = ThreadingHTTPServer((self.host, self.port), DLNARequestHandler)
+        self._httpd.daemon_threads = True
+        self._httpd.app = self  # type: ignore[attr-defined]
+        self.port = self._httpd.server_address[1]  # resolves port=0
+        threading.Thread(
+            target=self._httpd.serve_forever, name="pydlna-http", daemon=True
+        ).start()
+        if advertise:
+            self._ssdp = SSDPResponder(udn=self.udn, location=f"{self.base_url}/device.xml")
+            self._ssdp.start()
+        logger.info("Serving '%s' at %s", self.name, self.base_url)
+
+    def serve_forever(self) -> None:
+        """Start (if needed) and block until ``stop()`` or Ctrl+C."""
+        self.start()
+        try:
+            threading.Event().wait()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self.stop()
+
+    def stop(self) -> None:
+        if self._ssdp is not None:
+            self._ssdp.stop()
+            self._ssdp.join(timeout=2)
+            self._ssdp = None
+        if self._httpd is not None:
+            self._httpd.shutdown()
+            self._httpd.server_close()
+            self._httpd = None