added some audio content documentation

ephes · Aug 4, 2023 · 98509f8 · 98509f8
1 parent e5eca2f
commit 98509f8
Show file tree

Hide file tree

Showing 3 changed files with 35 additions and 0 deletions.
diff --git a/docs/audio.rst b/docs/audio.rst
@@ -0,0 +1,33 @@
+*****
+Audio
+*****
+
+You can upload audio files to the server and play them back in the browser.
+
+Audio Models
+============
+
+Audio files are represented by the `Audio` model. Audio files have a `title`, a
+`subtitle`, `tags` and four file fields pointing to the file in different audio formats:
+
+* `m4a` - AAC, works best on Apple/iOS devices
+* `mp3` - MP3, works everywhere, but has no time index so the whole file has to be downloaded before playback can start
+* `oga` - OGG Vorbis, maybe remove this one because apple is now adding support for opus, too
+* `opus` - Opus, better quality per bitrate than all other formats, but not as well known as the others
+
+Since podcast feeds only support one audio file per episode, there is one feed
+per audio format. The feeds are generated automatically and can be found at
+`feed/podcast/<audio_format>/rss.xml`.
+
+Playback
+========
+
+For playback of audio content `Podlove Web Player <https://podlove.org/podlove-web-player/>`_
+version 4 is used.
+
+.. Hint::
+
+    Currently supported features:
+
+    * Chapter marks
+    * Download button
diff --git a/docs/features.rst b/docs/features.rst
@@ -8,5 +8,6 @@ Features
 .. include:: comments.rst
 .. include:: blog.rst
 .. include:: video.rst
+.. include:: audio.rst
 .. include:: themes.rst
 .. include:: management-commands.rst
diff --git a/docs/releases/0.2.17.rst b/docs/releases/0.2.17.rst
@@ -9,3 +9,4 @@ Improved plain theme.
 * Fixed the "land on last page by default" wagtail admin pagination bug #98
 * Fixed the broken chooser buttons for audio and video (wagtail 5.1, action-chooser class was removed from button) #98
 * Fixed duplicate chooser button for audio and video #98
+* Added some documentation for audio content