Updating Docs for commit a23a6a5 from refs/heads/main by aw-was-here

whatsnowplaying · Sep 9, 2024 · f6dca64 · f6dca64
commit f6dca64
Show file tree

Hide file tree

Showing 171 changed files with 24,397 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 376a4e9ede2344fa28c604d226392b45
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.nojekyll b/.nojekyll
diff --git a/_images/acoustidmb.png b/_images/acoustidmb.png
diff --git a/_images/artexamples.png b/_images/artexamples.png
diff --git a/_images/artist_title_request.png b/_images/artist_title_request.png
diff --git a/_images/artist_title_withquotes_request.png b/_images/artist_title_withquotes_request.png
diff --git a/_images/björk.png b/_images/björk.png
diff --git a/_images/cover-title-artist.png b/_images/cover-title-artist.png
diff --git a/_images/discogs.png b/_images/discogs.png
diff --git a/_images/djuced-dir.png b/_images/djuced-dir.png
diff --git a/_images/djuced-source-selection.png b/_images/djuced-source-selection.png
diff --git a/_images/djuced-textfile-output.png b/_images/djuced-textfile-output.png
diff --git a/_images/fanarttv.png b/_images/fanarttv.png
diff --git a/_images/filter.png b/_images/filter.png
diff --git a/_images/filterrecommended.png b/_images/filterrecommended.png
diff --git a/_images/general.png b/_images/general.png
diff --git a/_images/generic_request.png b/_images/generic_request.png
diff --git a/_images/icecast-butt-audio.png b/_images/icecast-butt-audio.png
diff --git a/_images/icecast-butt-stream.png b/_images/icecast-butt-stream.png
diff --git a/_images/icecast-input-source.png b/_images/icecast-input-source.png
diff --git a/_images/icecast-mixxx-activate.png b/_images/icecast-mixxx-activate.png
diff --git a/_images/icecast-mixxx-preferences.png b/_images/icecast-mixxx-preferences.png
diff --git a/_images/icecast-mode-selection-none.png b/_images/icecast-mode-selection-none.png
diff --git a/_images/icecast-traktor-activate.png b/_images/icecast-traktor-activate.png
diff --git a/_images/icecast-traktor-preferences.png b/_images/icecast-traktor-preferences.png
diff --git a/_images/just_title_request.png b/_images/just_title_request.png
diff --git a/_images/m3u-source-selection.png b/_images/m3u-source-selection.png
diff --git a/_images/m3u-source.png b/_images/m3u-source.png
diff --git a/_images/meerkatdj_256x256.png b/_images/meerkatdj_256x256.png
diff --git a/_images/menu.png b/_images/menu.png
diff --git a/_images/mpris2-input-source.png b/_images/mpris2-input-source.png
diff --git a/_images/mpris2-source-selection.png b/_images/mpris2-source-selection.png
diff --git a/_images/mtv-no-publisher.png b/_images/mtv-no-publisher.png
diff --git a/_images/mtv-with-cover.png b/_images/mtv-with-cover.png
diff --git a/_images/mtvfade.webp b/_images/mtvfade.webp
diff --git a/_images/obs-browser-settings.png b/_images/obs-browser-settings.png
diff --git a/_images/obsws.png b/_images/obsws.png
diff --git a/_images/prince-signotimes.png b/_images/prince-signotimes.png
diff --git a/_images/quirks.png b/_images/quirks.png
diff --git a/_images/requests_generic.png b/_images/requests_generic.png
diff --git a/_images/requests_settings.png b/_images/requests_settings.png
diff --git a/_images/serato-local.png b/_images/serato-local.png
diff --git a/_images/serato-remote.png b/_images/serato-remote.png
diff --git a/_images/serato-source-selection.png b/_images/serato-source-selection.png
diff --git a/_images/snpMac.gif b/_images/snpMac.gif
diff --git a/_images/snpWin.gif b/_images/snpWin.gif
diff --git a/_images/textoutput.png b/_images/textoutput.png
diff --git a/_images/theaudiodb.png b/_images/theaudiodb.png
diff --git a/_images/title_artist_request.png b/_images/title_artist_request.png
diff --git a/_images/title_by_artist_request.png b/_images/title_by_artist_request.png
diff --git a/_images/traktor.png b/_images/traktor.png
diff --git a/_images/twitchbot-account-settings.png b/_images/twitchbot-account-settings.png
diff --git a/_images/twitchbot_auth.png b/_images/twitchbot_auth.png
diff --git a/_images/twitchbot_chat.png b/_images/twitchbot_chat.png
diff --git a/_images/videoloop.webp b/_images/videoloop.webp
diff --git a/_images/virtualdj.png b/_images/virtualdj.png
diff --git a/_images/webserver.png b/_images/webserver.png
diff --git a/_images/wham-maxell.png b/_images/wham-maxell.png
diff --git a/_images/wnp_discord_settings.png b/_images/wnp_discord_settings.png
diff --git a/_sources/contact.rst.txt b/_sources/contact.rst.txt
@@ -0,0 +1,19 @@
+Contact
+=======
+
+
+Discord
+-------
+
+If you'd like to chat with people who use the software or get inspiration, there is now a
+`Discord <https://discord.gg/bGdgm64Erb>`_ server available!
+
+Github
+------
+
+The main repository page with has issues tracking for bug reports and feature requests is on `Whats Now Playing Github <https://github.com/whatsnowplaying/whats-now-playing>`_
+
+Twitch
+------
+
+You can always see what is under development in real time on `Modern Meerkat\'s Stream <https://twitch.tv/modernmeerkat>`_ .
diff --git a/_sources/extras/discogs.rst.txt b/_sources/extras/discogs.rst.txt
@@ -0,0 +1,16 @@
+Discogs
+=======
+
+.. image:: images/discogs.png
+   :target: images/discogs.png
+   :alt: Discogs Settings
+
+Provides: Biographies, Fan art, Thumbnails, Websites
+
+Media tags required: album and artist
+
+`Discogs <https://www.discogs.com>`_ is a well-known source for music release information, a
+marketplace, and more. Be aware of Discogs Terms of Use as linked to on
+their `API Page <https://www.discogs.com/developers>`_. All you need to do is
+`Get a personal access token <https://www.discogs.com/settings/developers>`_. Discogs uses a
+pure text-search; results may be somewhat unreliable.
diff --git a/_sources/extras/fanarttv.rst.txt b/_sources/extras/fanarttv.rst.txt
@@ -0,0 +1,15 @@
+fanart.tv
+=========
+
+.. image:: images/fanarttv.png
+   :target: images/fanarttv.png
+   :alt: fanart.tv Settings
+
+Provides: Banners, Fan art, Logos, and Thumbnails
+
+Media tags required: MusicBrainz Artist ID
+
+`fanart.tv <https://www.fanart.tv>`_ is a community project to provide high quality
+artwork for music and other media. It requires music be tagged with
+`MusicBrainz <https://www.musicbrainz.org>`_ artist ids. You will need a
+`Fanart API Key <https://fanart.tv/get-an-api-key/>`_ in order to use this service.
diff --git a/_sources/extras/generalinfo.rst.txt b/_sources/extras/generalinfo.rst.txt
@@ -0,0 +1,77 @@
+General Info About Artist Extras
+================================
+
+   IMPORTANT: Many settings in this section currently require a restart of the software in order to take effect.
+
+Need some extra content for audio-only DJing?  The artist extras plug-ins allow for
+near real-time downloads of banners, logos, thumbnails, and fan art based upon the
+artists of the track that is currently playing.
+
+Artwork Details
+---------------
+
+.. image:: images/artexamples.png
+   :target: images/artexamples.png
+   :alt: OBS screen with an example of each image type
+
+
+.. csv-table:: Image Resources
+   :header: "Type", "WebSocket URL", "Raw Image URL", "WS Height", "WS Width", "General Quality", "Description"
+
+   "Banners", "/artistbanner.htm", "/artistbanner.png", "200px", "No Max", "High", "Image usually with picture and name of artist."
+   "Fan Art", "/artistfanart.htm", "", "800px", "1280px", "Varies", "Most sites curate these to be of higher quality but low quality images do get in"
+   "Logos", "/artistlogo.htm", "/artistlogo.png",  "200px", "480px", "High", "Stylized text or image that represents the artist"
+   "Thumbnails", "/artistthumb.htm", "/artistthumb.png", "480px", "200px", "Varies", "Image of the artist"
+
+Notes:
+
+  - Raw image URLs are not scaled and represent the original format as downloaded.
+  - Enabling this feature may cause a slowdown during the Exit of the app in order to save work in progress.
+  - Tracks with multiple artists will download both sets of images. However, only one will be used for fanart,
+    banners, and logos.
+
+Biographies
+-----------
+
+Additionally, a biography of the artist may also be available. These biographies are
+also written by fans and may be brief or fairly detailed. The 'artistlongbio' value has the full content whereas the 'artistshortbio' has only the content that will fit in a single Twitch chat message.
+
+    NOTE: The short bio will end in a complete sentence as determined by a natural language toolkit.  One should be aware, however, that punctuation marks may occasionally trip it up so the last sentence may get truncated early.
+
+
+Timing
+------
+
+Most of the content is downloaded during the write delay time period as set in the
+`general settings <../settings/general.html>`_ . You may need to bump up the delay to give enough time to not have
+'empty' graphics.  In general:
+
+
+* Every time an artist is loaded as a track, the system will try to download any new art that was either skipped or missed. So all limits that are set are for that track's downloads.  All previously downloaded content will is saved locally for long periods of time.  (They will eventually be removed.)
+* Banners, Logos, and Thumbnails are determined once per track from whatever content has been downloaded just prior to announcement.
+* Fanart will start to download next and will rotate during the entire time that artist is being played.
+* Switching to a different track from the same artist pick new banners, logos, and thumbnails if they are available.
+* Collaborations will attempt (but it is not guaranteed!) to pull extras for both artists if the metadata of the track has more than one set of artists listed. For example, a track labeled with both David Bowie and Lou Reed should have both Bowie and Reed's images.
+
+At startup and every hour while running, the image cache will be verified so that image lookups remain fast.  This operation is completely local and will cause no extra network traffic.
+
+Generic Settings
+----------------
+
+Configuring this feature is more involved than many others due to the need to compensate for various hardware limitations such as CPU and network bandwidth vs the amount of time it takes for the content to be available.  The default settings are thought to be fairly conservative and work with most configurations that have relatively good Internet connectivity with a Write Delay of 5 seconds.
+
+Maximums:  the number of images to attempt to download at a given time out of the total set available. Banners, logos, and thumbnails are downloaded first, and then fan art will be downloaded. Any extra fan art will be downloaded.  The maximums should be low enough that the first set downloads prior to the track being announced and the fanart finishes downloading prior to the next track being selected.
+
+Download processes: The number of background processes to run that do nothing but download art and update the backend storage.  This number should be configured high enough to get all of the first pass of downloads done quickly but low enough that it doesn't overwhelm
+
+Image cache size in GB: The amount of space to use for images.  In general, every 1GB will store approximately 1,000 mixed size images.
+
+The 'Clear Cache' button will remove all mappings between artists and images.  It does not remove the cached responses from the web server in order to save bandwidth.
+
+Reminder
+--------
+
+In order to perform these look ups, certain data is required to be tagged in the media to
+make the results remotely accurate.  More data == more better results.  Therefore, media
+with ISRC tags will cause MusicBrainz lookups if that service is enabled to fill in
+any missing data.
diff --git a/_sources/extras/index.rst.txt b/_sources/extras/index.rst.txt
@@ -0,0 +1,13 @@
+Artist Extras
+=============
+
+**What's Now Playing** can retrieve extra content for your streams:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   generalinfo
+   discogs
+   fanarttv
+   theaudiodb
diff --git a/_sources/extras/theaudiodb.rst.txt b/_sources/extras/theaudiodb.rst.txt
@@ -0,0 +1,16 @@
+TheAudioDB
+==========
+
+.. image:: images/theaudiodb.png
+   :target: images/theaudiodb.png
+   :alt: theaudiodb Settings
+
+Provides: Banners, Biographies, Fan art, Logos, Thumbnails, and Websites
+
+Media tags required: artist or MusicBrainz Artist ID
+
+`TheAudioDB <https://www.theaudiodb.com>`_ is a community project to provide high quality
+artwork and other metadata for music. If `MusicBrainz <https://www.musicbrainz.org>`_
+artist ids are available, it will use that information to increase accuracy. You will need a
+`TheAudioDB API Key <https://www.theaudiodb.com/api_guide.php>`_ in order to use this service.
+
diff --git a/_sources/gallery.rst.txt b/_sources/gallery.rst.txt
@@ -0,0 +1,68 @@
+Gallery of Templates
+====================
+
+**What's Now Playing** has quite a bit of flexibility in what kind of output
+you can generate to the point that there are nearly infinite possibilities.
+The text versions are meant to be used to feed other systems and are rather
+basic.  E.g., the basic text template generates:
+
+ Utah Saints - Something Good '08
+
+Picking that template, configuring a text source, configuring a scroll filter
+on that source, and then writing to it via OBS WebSocket allows one to do:
+
+.. image:: gallery/images/videoloop.webp
+   :target: gallery/images/videoloop.webp
+   :alt: Scroll demo
+
+For the HTML templates, there are generally two varieties, one that uses
+WebSockets (start with ws-)
+and those that do not.  WebSocket varieties are more likely to get updates closer
+in sync with the rest of your display. However, older software stacks may
+not support WebSockets.
+
+AAdditionally, the templates are typically named to have 'fade' or 'nofade'.
+'Nofade' generally stay on the screen for the duration of the song.  'Fade'
+will appear for a while and then disappear, only to reappear when the song changes:
+
+.. image:: gallery/images/mtvfade.webp
+   :target: gallery/images/mtvfade.webp
+   :alt: Fading example
+
+
+Here are some pictures of the bundled HTML template files
+being used with an OBS stream.
+
+* cover-title-artist:
+
+.. image:: gallery/images/cover-title-artist.png
+   :target: gallery/images/cover-title-artist.png
+   :alt: Example cover with just title and artist and solid background Image
+
+* mtv:
+
+.. image:: gallery/images/mtv-no-publisher.png
+   :target: gallery/images/mtv-no-publisher.png
+   :alt: Example MTV-style with no publisher Image
+
+* mtv-cover:
+
+.. image:: gallery/images/mtv-with-cover.png
+   :target: gallery/images/mtv-with-cover.png
+   :alt: Example MTV-style with cover Image
+
+The software writes output in UTF-8. That covers the vast majority of characters that one may hit.  Be aware
+that OBS and other software may need to have their settings, such as fonts, changed to support
+non-ASCII characters!
+
+.. image:: gallery/images/björk.png
+   :target: gallery/images/björk.png
+   :alt: Björk
+
+.. image:: gallery/images/wham-maxell.png
+   :target: gallery/images/wham-maxell.png
+   :alt: WHAM! Ad in Japanese
+
+.. image:: gallery/images/prince-signotimes.png
+   :target: gallery/images/prince-signotimes.png
+   :alt: Prince Peace Sign
diff --git a/_sources/help/accuracy.rst.txt b/_sources/help/accuracy.rst.txt
@@ -0,0 +1,51 @@
+Improving Accuracy
+==================
+
+The general rule is:  the more data in, the better data out.  A few metadata tags go a very long way. In order
+of most important to least important:
+
+1. `Musicbrainz <https://musicbrainz.org//>`_ Recording IDs
+2. `International Standard Recording Codes <https://isrc.ifpi.org/en/>`_ aka ISRCs
+3. Album + Artist + Title
+4. Artist + Title
+5. Title
+
+Even after all of that, sometimes things that you think should be found aren't, such as cover art.
+Unlike a lot of software, **What's Now Playing** errs on the side of caution.
+
+For example of what I mean, let's take a real world example.  While
+testing some of the audio recognition and metadata downloading capabilities,
+`Pet Shop Boys - "Vocal" <https://www.youtube.com/watch?v=qNR8gQAoYCs>`_ was used as an input with no
+modification the metadata (so, in other words, very much wrong and very much a mess).
+Virtual DJ reported the song came from the album
+`Electric <https://musicbrainz.org/release/eeb0aa28-b7c9-4109-b8a6-e08611a6ca84>`_ and
+provided the cover art for that album.  **What's Now Playing** with AcoustID enabled reported that
+the song was actually "Vocal (Radio Edit)" and appears on the album
+`Spex CD #110 <https://musicbrainz.org/release/2ccfa7d1-8918-4c41-9945-e302a6053bd8>`_.
+Since (at least as of this writing) that album does not have cover art, no cover art was provided.
+
+Which one is correct? Neither and both. It really depends upon the individual DJ's goals.  From a
+software perspective, they are both an answer to the cover art question. It also demonstrates how
+a bit of manipulation of the title can yield very different results.
+
+This example is also important when working with systems such as Deezer, Tidal, etc, or even WinMedia as
+(ultimately) the source of your music.  In the listing above, we are almost always at #4 since many
+pieces of the software involved do not provide the album information.  Since there is no other
+information, it can sometimes be a bit hit or miss.
+
+For white labels, mixes, etc, the software will try as much as it can to locate something but that
+isn't always successful.  In most cases, artist information is usually available.  For mixes that
+are more than one person (e.g., "A vs B"-types), the software will generally pick _one_.
+
+In general, the primary principal thus far has been:  if the actual track can't be found, then supply
+artist-level data.  If nothing about the artist can be found, then supply nothing extra.
+
+Note that when it comes to finding the actual track: the more precise the better. For example:
+
+  * The Farm's "All Together Now" vs. "Altogether Now"
+  * Prince "Purple Rain" vs. Prince and the Revolution "Purple Rain"
+
+Each of those give slightly different results.
+
+Improving the quality of the data is an ongoing project.  If you see something that you think _should_
+work but doesn't, feel free to submit a `bug report <bugreports.html>`_ or visit `discord <../contact.html>`_
diff --git a/_sources/help/bugreports.rst.txt b/_sources/help/bugreports.rst.txt
@@ -0,0 +1,9 @@
+Bug Reports and Feature Requests
+================================
+
+**What's Now Playing** is `open source software <https://opensource.com/resources/what-open-source>`_ .
+That means unlike commercial software individuals have the capability to
+contribute in a variety of ways.  Currently this project is hosted
+on  `Github <https://github.com/whatsnowplaying/whats-now-playing>`_ which provides
+access to the source code, bugs and feature requests (issues), and a discussion
+area where you can ask questions.
diff --git a/_sources/help/developers.rst.txt b/_sources/help/developers.rst.txt
@@ -0,0 +1,89 @@
+
+Developers
+==========
+
+       NOTE: For people familiar with Python, it is HIGHLY RECOMMENDED that you use and
+       build with venv due to the restrictive requirements of the tested packages listing.
+       While newer versions MAY work, there is no guarantee that PyInstaller and other
+       utilities will build a proper executable.
+
+Development Requirements
+------------------------
+
+To locally build and install **What's Now Playing**\ , you will need the following:
+
+#. Python for your operating system (3.10 or 3.11 is required.  3.12 has issues)
+#. Access to a development shell (e.g., /Applications/Utility/Terminal on OS X)
+#. ``git`` installed and working
+
+Linux Pre-work
+^^^^^^^^^^^^^^
+
+If you are on Linux, it is recommended that you install dbus-python at
+the system level first to get the basic OS requirements put in
+place first.  For example, for Debian-style systems:
+
+.. code-block:: bash
+
+   sudo apt-get install python-dbus
+
+macOS Pre-work
+^^^^^^^^^^^^^^
+
+You will need a working, modern ICU library:
+
+1. ``brew install icu4c``
+2. ``export PKG_CONFIG_PATH=/usr/homebrew/opt/icu4c/lib/pkgconfig``
+
+Commands
+--------
+
+.. code-block:: bash
+
+   python -m venv (virtualenv directory)
+   source (virtualenv directory)/bin/activate
+   git clone https://github.com/whastnowplaying/whats-now-playing.git
+   cd whats-now-playing
+   git checkout [version]
+   pip install ".[dev,docs,osspecials,test]
+
+At this point, you should be able to run the software from the shell:
+
+.. code-block:: bash
+
+   NowPlaying
+
+Build Executable
+----------------
+
+To build a stand-alone executable, there is a helper script to do all the work:
+
+* macOS
+
+.. code-block:: bash
+
+   builder.sh macosx
+
+* Windows
+
+
+.. code-block:: bash
+
+   builder.sh windows
+
+* Other
+
+.. code-block:: bash
+
+   builder.sh
+
+This bash script will:
+
+1. Create a venv
+2. Install the contents of the venv
+3. Run PyInstaller
+
+In the end you should have a zip file with your newly built binary.
+
+There should now be a ``dist`` directory and inside that directory will be
+either a ``NowPlaying.app`` on OS X or just a ``NowPlaying`` single file.