Development =========== .. _design: Design ------ .. _meta data: Meta Data """"""""" This feature is enabled on a per encoder or per device basis with the ``track_metadata`` option set to ``yes``. It is enabled by default. When ``pa-dlna`` receives a ``change`` event from pulseaudio and this event is related to a change to the meta data as for example when a new track starts with a new song, the following sequence of events occurs: * ``pa-dlna``: + Writes the last chunk to the HTTP socket (see `Chunked Transfer Coding`_) and sends a ``SetNextAVTransportURI`` SOAP action with the new meta data. + Upon receiving the HTTP GET request from the device, instantiates a new Track and starts a task to run the pulseaudio stream. * The DLNA device: + Gets the ``SetNextAVTransportURI`` with the new meta data and sends a GET request to start a new HTTP session for the next track while still playing the current track from its read buffer. + Still playing the current track, pre-loads the read buffer of the new HTTP session. + Upon receiving the last chunk for the current track, starts playing the next track. This way, the last part of the current track is not truncated by the amount of latency introduced by the device's read buffer and the delay introduced by filling the read buffer of the next track is minimized. Asyncio Tasks """"""""""""" Task names in **bold** characters indicate that there is one such task for each DLNA device, when in *italics* that there may be such tasks for each DLNA device. UPnPControlPoint tasks: ================ ====================================================== ssdp notify Monitor reception of NOTIFY SSDPs. ssdp msearch Send MSEARCH SSDPs at regular intervals. **root devices** Implement control of the aging of an UPnP root device. ================ ====================================================== AVControlPoint tasks: ================ ====================================================== main Instantiate the UPnPControlPoint that starts the UPnP tasks. |br| Create the pulse task, the http_server task, the renderer tasks. |br| Create the shutdown task. |br| Handle UPnP notifications. pulse Monitor pulseaudio sink-input events. *maybe_stop* Handle a ``remove`` pulse event. *http_server* Serve DLNA HTTP requests, one task per IP address. |br| Start the client_connected tasks. **renderers** Act upon pulseaudio events. |br| Run UPnP SOAP actions. abort Abort the pa-dlna program. shutdown Wait on event pushed by the signal handlers. ================ ====================================================== HTTPServer tasks: ================== ====================================================== *client_connected* HTTPServer callback wrapped by asyncio in a task. |br| Start the StreamSession tasks: |br| ``parec | encoder program | HTTP socket``. ================== ====================================================== StreamSession tasks: ==================== ==================================================== *parec process* Start the parec process and wait for its exit. *parec log_stderr* Log the parec process stderr. *encoder process* Start the encoder process and wait for its exit. *encoder log_stderr* Log the encoder process stderr. *track* Write the audio stream to the HTTP socket. ==================== ==================================================== Track tasks: ============== ====================================================== *shutdown* Write the last chunk and close the HTTP socket. ============== ====================================================== DLNA Device Registration """""""""""""""""""""""" For a new DLNA device to be registered, ``pa-dlna`` must establish the **local** network address to be used in the URL that must be advertised to the DLNA device in the ``SetAVTransportURI`` and ``SetNextAVTransportURI`` SOAP actions, so that the DLNA device may initiate the HTTP session and start the streaming. This depends on which event triggered this registration: Reception of the unicast response to an UPnP MSEARCH SSDP. The destination address of the SSDP response is the address that is being looked for. MSEARCH SSDP are sent by ``pa-dlna`` every 60 seconds (default). Reception of an UPnP NOTIFY SSDP, broadcasted by the device [#]_. The DLNA device can be registered only if the source address of this packet belongs to one of the subnets of the network interfaces. That is, the DLNA device and the host belong to the same subnet on this interface and the local IP address on this subnet is the address that is being looked for. The `UPnP Device Architecture`_ specification does not specify the periodicity of NOTIFY SSDPs sent by DLNA devices. Development process [#]_ ------------------------ Requirements """""""""""" Development: * `curl`_ and `ffmpeg`_ are used by some tests of the test suite. When missing, those tests are skipped. `curl`_ is also needed when releasing a new version to fetch the GitLab test coverage badge. * `ffmpeg`_, the `Upmpdcli`_ DLNA Media Renderer, the `MPD`_ Music Player Daemon and a running Pulseaudio or PipeWire sound server are needed to run the tests of the ``test_tracks`` Python module (otherwise those tests are skipped). An audio track sourced by ffmpeg is streamed by pa-dlna to the Upmpdcli DLNA that outputs the stream to MPD, which in turn outputs the stream to a PulseAudio/PipeWire sink created by ``test_tracks``. Monitoring the state of this sink allows checking that the audio track does follow this path. This scenario may be run at the debug log level with the following command:: $ python -m pa_dlna.tests.test_tracks [EncoderName] * `pactl`_ is needed to run the tests that connect to the pulseaudio or pipewire sound server. When missing, those tests are skipped. * `docker`_ may be used to run the test suite in a pulseaudio or pipewire debian container. Follow the instructions written as comments in each of the ``Dockerfile.pulse`` and ``Dockerfile.pipewire`` Docker files. * `coverage`_ is used to get the test suite coverage. * `python-packaging`_ is used to set the development version name as conform to PEP 440. * `flit`_ is used to publish pa-dlna to PyPi and may be used to install pa-dlna locally. At the root of the pa-dlna git repository, use the following command to install pa-dlna locally:: $ flit install --symlink [--python path/to/python] This symlinks pa-dlna into site-packages rather than copying it, so that you can test changes by running the ``pa-dlna`` and ``upnp-cmd`` commands provided that the ``PATH`` environment variable holds ``$HOME/.local/bin``. Otherwise without using `flit`_, one can run those commands from the root of the repository as:: $ python -m pa_dlna.pa_dlna $ python -m pa_dlna.upnp_cmd Documentation: * `Sphinx`_ [#]_. * `Read the Docs theme`_. * Building the pdf documentation: - The latex texlive package group. - Imagemagick version 7 or more recent. Documentation """"""""""""" To build locally the documentation follow these steps: - Generate the ``default-config.rst`` file:: $ python -m tools.gendoc_default_config - Fetch the GitLab test coverage badge:: $ curl -o images/coverage.svg "https://gitlab.com/xdegaye/pa-dlna/badges/master/coverage.svg?min_medium=85&min_acceptable=90&min_good=90" $ magick images/coverage.svg images/coverage.png - Build the html documentation and the man pages:: $ make -C docs clean html man latexpdf Updating development version """""""""""""""""""""""""""" Run the following commands to update the version name at `latest documentation`_ after a bug fix or a change in the features:: $ python -m tools.set_devpt_version_name $ make -C docs clean html man latexpdf $ git commit -m "Update development version name" $ git push Releasing """"""""" * Run the test suite from the root of the project [#]_:: $ python -m unittest --verbose --catch --failfast * Get the test suite coverage:: $ coverage run --include="./*" -m unittest $ coverage report -m * Update ``__version__`` in pa_dlna/__init__.py. * When this new release depends on a more recent libpulse release than previously: + Update ``MIN_LIBPULSE_VERSION`` in pa_dlna/__init__.py. + Update the minimum required libpulse version in pyproject.toml. * Update docs/source/history.rst if needed. * Build locally the documentation, see one of the previous sections. * Commit the changes:: $ git commit -m 'Version 1.n' $ git push * Tag the release and push:: $ git tag -a 1.n -m 'Version 1.n' $ git push --tags * Publish the new version to PyPi:: $ flit publish .. include:: common.txt .. _Chunked Transfer Coding: https://www.rfc-editor.org/rfc/rfc2616#section-3.6.1 .. _Read the Docs theme: https://docs.readthedocs.io/en/stable/faq.html#i-want-to-use-the-read-the-docs-theme-locally .. _Sphinx: https://www.sphinx-doc.org/ .. _curl: https://curl.se/ .. _pactl: https://linux.die.net/man/1/pactl .. _docker: https://docs.docker.com/build/guide/intro/ .. _`coverage`: https://pypi.org/project/coverage/ .. _flit: https://pypi.org/project/flit/ .. _unittest command line options: https://docs.python.org/3/library/unittest.html#command-line-options .. _latest documentation: https://pa-dlna.readthedocs.io/en/latest/ .. _python-packaging: https://github.com/pypa/packaging .. _ffmpeg: https://www.ffmpeg.org/ffmpeg.html .. _Upmpdcli: https://www.lesbonscomptes.com/upmpdcli/ .. _MPD: https://mpd.readthedocs.io/en/latest/user.html .. rubric:: Footnotes .. [#] All sockets bound to the notify multicast address receive the datagram sent by a DLNA device, even though it has been received by only one interface at the physical layer. .. [#] The shell commands in this section are all run from the root of the repository. .. [#] Required versions at ``docs/requirements.txt``. .. [#] See `unittest command line options`_.