docs: add Podcasts feature

app/Console/Commands/SyncPodcastsCommand.php

@@ -11,6 +11,7 @@ use Throwable;
 class SyncPodcastsCommand extends Command
 {
     protected $signature = 'koel:podcasts:sync';
+    protected $description = 'Synchronize podcasts.';
 
     public function __construct(private readonly PodcastService $podcastService)
     {

docs/.vitepress/components/InterfaceIcon.vue

@@ -1,11 +1,13 @@
 <template>
   <span>
-    <img class="inline border-0 rounded-0" :src="src">
+    <img class="inline border-0 rounded-0" v-bind="$attrs">
   </span>
 </template>
 
 <script lang="ts" setup>
-defineProps<{ src: string }>()
+defineOptions({
+  inheritAttrs: false
+})
 </script>
 
 <style scoped>

docs/.vitepress/config.mts

@@ -62,6 +62,7 @@ export default defineConfig({
           { text: 'Instant Search', link: '/usage/search' },
           { text: 'Themes', link: '/usage/themes' },
           { text: 'Artist, Album, & Playlist Arts', link: '/usage/artist-album-playlist-arts' },
+          { text: 'Podcasts', link: '/usage/podcasts' },
           { text: 'User Management', link: '/usage/user-management' },
           { text: 'Profile & Preferences', link: '/usage/profile-preferences' },
           { text: 'Remote Controller', link: '/usage/remote-controller' },

docs/assets/icons/plus-circle.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path class="" fill="currentColor" d="M256 512c141.4 0 256-114.6 256-256S397.4 0 256 0S0 114.6 0 256S114.6 512 256 512zM232 344V280H168c-13.3 0-24-10.7-24-24s10.7-24 24-24h64V168c0-13.3 10.7-24 24-24s24 10.7 24 24v64h64c13.3 0 24 10.7 24 24s-10.7 24-24 24H280v64c0 13.3-10.7 24-24 24s-24-10.7-24-24z"></path></svg>

docs/assets/icons/plus.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path class="" fill="currentColor" d="M256 512c141.4 0 256-114.6 256-256S397.4 0 256 0S0 114.6 0 256S114.6 512 256 512zM232 344V280H168c-13.3 0-24-10.7-24-24s10.7-24 24-24h64V168c0-13.3 10.7-24 24-24s24 10.7 24 24v64h64c13.3 0 24 10.7 24 24s-10.7 24-24 24H280v64c0 13.3-10.7 24-24 24s-24-10.7-24-24z"></path></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path class="" fill="currentColor" d="M256 80c0-17.7-14.3-32-32-32s-32 14.3-32 32V224H48c-17.7 0-32 14.3-32 32s14.3 32 32 32H192V432c0 17.7 14.3 32 32 32s32-14.3 32-32V288H400c17.7 0 32-14.3 32-32s-14.3-32-32-32H256V80z"></path></svg>

docs/assets/icons/refresh.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path class="" fill="currentColor" d="M463.5 224H472c13.3 0 24-10.7 24-24V72c0-9.7-5.8-18.5-14.8-22.2s-19.3-1.7-26.2 5.2L413.4 96.6c-87.6-86.5-228.7-86.2-315.8 1c-87.5 87.5-87.5 229.3 0 316.8s229.3 87.5 316.8 0c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0c-62.5 62.5-163.8 62.5-226.3 0s-62.5-163.8 0-226.3c62.2-62.2 162.7-62.5 225.3-1L327 183c-6.9 6.9-8.9 17.2-5.2 26.2s12.5 14.8 22.2 14.8H463.5z"></path></svg>

docs/cli-commands.md

@@ -4,7 +4,7 @@ outline: [2, 3]
 
 # CLI Commands
 
-Koel comes with a set of handy CLI commands to help you manage your installation. 
+Koel comes with a set of handy CLI commands to help you manage your installation.
 These commands are available via Laravel’s `artisan` command line interface.
 
 You can run `php artisan list` from your Koel installation directory and pipe the output to `grep` to filter out those under the `koel` namespace:
@@ -17,6 +17,7 @@ php artisan list | grep koel
   koel:license:activate       Activate a Koel Plus license
   koel:license:deactivate     Deactivate the currently active Koel Plus license
   koel:license:status         Check the current Koel Plus license status
+  koel:podcasts:sync          Synchronize podcasts.
   koel:prune                  Remove empty artists and albums
   ...
 ```
@@ -91,6 +92,16 @@ Check the current Koel Plus license status.
 php artisan koel:license:status
 ```
 
+### `koel:podcasts:sync`
+
+Synchronize podcasts.
+
+#### Usage
+
+```bash
+php artisan koel:podcasts:sync
+```
+
 ### `koel:prune`
 
 Remove empty artists and albums.
@@ -188,7 +199,7 @@ php artisan koel:tags:collect
 ## Command Scheduling
 
 Some of the commands, such as `koel:scan` and `koel:prune`, can be scheduled to run at regular intervals.
-Koel uses Laravel’s built-in scheduler to manage this. 
+Koel uses Laravel’s built-in scheduler to manage this.
 
 In order to set up the scheduler, you need to add the following cron entry to your server:
 
@@ -196,7 +207,7 @@ In order to set up the scheduler, you need to add the following cron entry to yo
 * * * * * cd /path-to-koel-installation && php artisan schedule:run >> /dev/null 2>&1
 ```
 
-This will run the scheduler every minute, which will then run any scheduled commands as needed. 
-By default, `koel:scan` and `koel:prune` are set to run every day at midnight.
+This will run the scheduler every minute, which will then run any scheduled commands as needed.
+By default, `koel:scan`, `koel:prune`, and `koel:podcasts:sync` are set to run every day at midnight.
 
 Though you can still manually set up cron jobs for individual commands, the scheduler is the recommended approach to command scheduling in Koel, as it will automatically cover any commands that may be added in the future.

docs/usage/podcasts.md

@@ -0,0 +1,40 @@
+# Podcasts
+
+Aside from music, Koel also supports podcast streaming. This feature is still in its early stages, so expect more improvements in the future.
+
+![Podcasts](../assets/img/podcasts.avif)
+
+## Subscribe to a Podcast
+
+To subscribe to a podcast, click the <InterfaceIcon :src="plusIcon" /> button on the top right of the "Podcasts" page and enter the podcast's RSS feed URL.
+You can find the RSS feed URL on the podcast's website or by searching for it with your favorite search engine.
+Note that Koel doesn't support proprietary podcast services like Spotify or Apple Podcasts.
+
+:::warning
+Podcast parsing can be time-consuming, and not all podcasts are created equal.
+If the process errors out, check [Troubleshooting](../troubleshooting#first-steps) for help.
+:::
+
+After successful subscription, you will be able to browse the podcast's episodes and stream them directly from Koel.
+
+## Listening to Podcasts
+
+Koel treats podcast episodes not much differently from songs. You can stream them, mark them as favorites, add them to playlists, search for them etc. using the same
+[interface elements](./web-interface.md). However, there are some main differences:
+
+* Koel maintains the last played position for each episode, so you can resume listening where you left off.
+* Smart playlists don't work with podcasts and will not contain podcast episodes.
+* You can't edit the metadata of podcasts and episodes like you can with songs.
+* Podcast episodes don't have "genres" (though they may have categories), so you can't browse them by genre.
+* [Playlist collaboration](../plus/collaboration) <PlusBadge /> doesn't work with podcasts.
+* When streaming an episode, Koel will first try with its original source and only download it to your server if a CORS error occurs in the attempt. This means that you can stream podcasts without worrying about your server's storage space, but your streaming experience will depend on the podcast's hosting service.
+
+## Updating Podcasts
+
+If you have Koel's [command scheduler](../cli-commands.md#command-scheduling) set up, the `koel:podcasts:sync` command will automatically run at midnight to keep your podcasts up to date.
+You can also update a podcast's episodes manually from the web interface by clicking the <InterfaceIcon :src="refreshIcon" alt="Refresh" /> button on the podcast's page.
+
+<script lang="ts" setup>
+import refreshIcon from '../assets/icons/refresh.svg'
+</script>
+

docs/usage/web-interface.md

@@ -30,7 +30,7 @@ like the artist or album's information when [configured](../service-integrations
 On any screen with a song list (a "song-list screen") you can:
 
 * Sort the list by clicking on the column headers
-* Filter the list by typing in the filter box (marked with <InterfaceIcon :src="filterIcon" />)
+* Filter the list by typing in the filter box (marked with <InterfaceIcon :src="filterIcon" alt="Filter" />)
 * Select a song by clicking on it. To select multiple songs, hold down <kbd>Shift</kbd> or <kbd>Ctrl/Cmd</kbd> while clicking.
 * Drag and drop one or more songs to reorder them when applicable
 * Drag and drop one or more songs to applicable menu items to the left to perform actions like adding to a playlist, queueing, or marking them as favorite
@@ -44,7 +44,7 @@ Play a song by double-clicking on it or pressing <kbd>Enter</kbd> on either a so
 Queue a song (or multiple songs) by right-clicking and choose one of the Queue options, or by dragging and dropping it
 into the queue menu item.
 
-You can use the dedicated button (with the <InterfaceIcon :src="shuffleIcon" /> icon) to shuffle the current list or the selected songs.
+You can use the dedicated button (with the <InterfaceIcon :src="shuffleIcon" alt="Shuffle" /> icon) to shuffle the current list or the selected songs.
 To play in order instead of shuffling, hold down <kbd>Alt/Option</kbd> while clicking the button.
 
 When a song is playing, you can control playback using the buttons at the bottom of the screen as well as
@@ -54,19 +54,19 @@ rewind/fast-forward the song by clicking and dragging the progress bar.
 
 From the same area, you also can:
 
-* <InterfaceIcon :src="heartIcon" /> like/unlike the current song
-* <InterfaceIcon :src="volumeIcon" /> control the volume
-* <InterfaceIcon :src="repeatIcon" /> switch between repeat modes
-* <InterfaceIcon :src="slidersIcon" /> show the equalizer
-* <InterfaceIcon :src="boltIcon" /> show the visualizer
-* <InterfaceIcon :src="expandIcon" /> toggle full-screen mode
+* <InterfaceIcon :src="heartIcon" alt="Heart" /> like/unlike the current song
+* <InterfaceIcon :src="volumeIcon" alt="Volume" /> control the volume
+* <InterfaceIcon :src="repeatIcon" alt="Repeat" /> switch between repeat modes
+* <InterfaceIcon :src="slidersIcon" alt="Sliders" /> show the equalizer
+* <InterfaceIcon :src="boltIcon" alt="Bolt" /> show the visualizer
+* <InterfaceIcon :src="expandIcon" alt="Expand" /> toggle full-screen mode
 
 Right-clicking the footer area brings up context menu for the currently playing song.
 
 ## Creating and Managing Playlists
 
 Koel supports creating an unlimited number of playlists as well as organizing them into folders.
-Start by clicking the <InterfaceIcon :src="plusIcon" /> button next to the "Playlists" header in the navigation bar. You'll be provided with three options:
+Start by clicking the <InterfaceIcon :src="plusIcon" alt="Add" /> button next to the "Playlists" header in the navigation bar. You'll be provided with three options:
 
 * "New Playlist…" brings up a dialog to create a standard playlist
 * "New Smart Playlist…" brings up a dialog to create a smart playlist
@@ -149,13 +149,13 @@ or a textarea.
 With a browser that supports [MediaSession](https://developer.mozilla.org/en-US/docs/Web/API/MediaSession) — basically, all modern browsers — you can control Koel using hardware media keys without even having Koel _or the browser_ focused.
 
 <script lang="ts" setup>
-import shuffleIcon from '../assets/icons/shuffle.svg'
-import filterIcon from '../assets/icons/filter.svg'
 import boltIcon from '../assets/icons/bolt.svg'
 import expandIcon from '../assets/icons/expand.svg'
+import filterIcon from '../assets/icons/filter.svg'
 import heartIcon from '../assets/icons/heart.svg'
+import plusIcon from '../assets/icons/plus-circle.svg'
 import repeatIcon from '../assets/icons/repeat.svg'
+import shuffleIcon from '../assets/icons/shuffle.svg'
 import slidersIcon from '../assets/icons/sliders.svg'
 import volumeIcon from '../assets/icons/volume.svg'
-import plusIcon from '../assets/icons/plus.svg'
 </script>