diff --git a/README.md b/README.md new file mode 100644 index 0000000..1f95665 --- /dev/null +++ b/README.md @@ -0,0 +1,32 @@ +# Podcaster +## A Kirby podcast plugin + +![GitHub release](https://img.shields.io/github/release/mauricerenck/podcaster.svg?maxAge=1800) ![License](https://img.shields.io/github/license/mashape/apistatus.svg) ![Kirby Version](https://img.shields.io/badge/Kirby-3.9%2B-black.svg) + +--- + +## Installation + +Use one of these three methods to install the plugin: + +- composer (recommended): `composer require mauricerenck/podcaster` +- zip file: download the [latest release](https://github.com/mauricerenck/podcaster/releases) unzip it, copy it to `site/plugins/podcaster` + +--- + +## Upgrade from version 2 + +There are major changes from version 2 to version 3. Although I tried to make the plugin backwards compatible as good as possible, there are some breaking changes. **So please read the migration guide before installing this version!** + +--- + +## Setup + +There is a full video guide on setting up your podcast step by step on the Podcaster Website + +TODO Screenshot of one video with link to site + +* [Migrate from version 2](docs/migration-v2-v3.md) +* [Setup your podcast](docs/setup.md) +* [All options and settings](docs/options.md) +* [FAQ](docs/faq.md) \ No newline at end of file diff --git a/app/PodcasterStats.php b/app/PodcasterStats.php index bd624d3..8c715d1 100644 --- a/app/PodcasterStats.php +++ b/app/PodcasterStats.php @@ -38,7 +38,6 @@ public function trackFeed($feed): void } if (option('mauricerenck.podcaster.statsInternal') === true) { - $trackingDate = time(); $this->upsertFeed($feed); } diff --git a/blueprints/pages/feed.yml b/blueprints/pages/feed.yml index e5b37ae..9e6bca2 100644 --- a/blueprints/pages/feed.yml +++ b/blueprints/pages/feed.yml @@ -2,6 +2,5 @@ title: Podcaster Feed tabs: details: tabs/podcaster/feed-details basic: tabs/podcaster/feed-base - stats: tabs/podcaster/feed-stats player: tabs/podcaster/feed-player tracking: tabs/podcaster/feed-tracking diff --git a/blueprints/tabs/feed-player.yml b/blueprints/tabs/feed-player.yml index 56b7a1b..b443d45 100644 --- a/blueprints/tabs/feed-player.yml +++ b/blueprints/tabs/feed-player.yml @@ -103,6 +103,7 @@ columns: label: Service podcasterPodloveShareChannels: + label: Share Channels type: multiselect options: facebook: Facebook @@ -114,6 +115,7 @@ columns: mail: Mail link: Link podcasterPodloveSharePlaytime: + label: Share Playtime type: toggle default: yes text: diff --git a/docs/assets/podlove-fonts.png b/docs/assets/podlove-fonts.png new file mode 100644 index 0000000..115188a Binary files /dev/null and b/docs/assets/podlove-fonts.png differ diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..b5642ca --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,5 @@ +# FAQ + +## How to disable connections to api.podcaster-plugin.com? +You have to use your own blueprints and use the local files stored with the plugin. The remote ones are used to make sure they are always up to date. + diff --git a/docs/feed.md b/docs/feed.md index 56b38a3..1632f10 100644 --- a/docs/feed.md +++ b/docs/feed.md @@ -4,7 +4,7 @@ To use Kirbys UUIDs as GUID in the feed, set this option in your config: `'mauricerenck.podcaster.feed.uuid' => true` -default is false for backwarts compatibility +The default is false for backwards compatibility -changing this on a published podcast may result in duplicated episodes in Apple Podcasts as the GUID value should always be unique +Changing this on a published podcast may result in duplicated episodes in a Podcatcher as the GUID value should always be unique diff --git a/docs/migration-v2-v3.md b/docs/migration-v2-v3.md new file mode 100644 index 0000000..22f2211 --- /dev/null +++ b/docs/migration-v2-v3.md @@ -0,0 +1,48 @@ +# Migration + +The update from version 2 is a huge one. A lot of things changed within the Kirby system in the last months. **So make sure to backup your files and your database before updating.** I also recommend to do this update on a test environment first. + +## Update the plugin +The easiest way to update the plugin is to use composer. If you didn't install it with composer, downloads the latest version and replace the podcaster folder within `site/plugins`. + +Podcaster 3 needs PHP 8.x and Kirby 3.8 or upwards. + +## Running migrations +If you use the internal stats feature make sure to create a backup of your existing database BEFORE installing the plugin. Installing the plugin and opening the site or the panel will start the migration progress. So please be aware of that. + +The database structure changed a lot. While migration the new structure will be applied and existing data will be migrated if needed. If your database has a lot of entries, this can take some time. I would recommend not doing this on a live system, but run the migration locally and: + +1. Use a local copy of your database to perform the migration. Afterwards you can overwrite the production database with the locally migrated one +2. Connect to the remote database locally and run the migration on your local machine. Be aware this can lead to errors on production during the time your database has the new structure but your production plugin is not updated yet. + +You can also run the migration on the production system, but you should not do this during times of high load. + +## Sanitize database +When migrating without the sanitize option you will see a lot of empty fields in your old tracking entries. This won't affect the functionality of the plugin, but you might see some missing labels or data in the analytics view. + +There is a script which tries to convert this data. To do so enable this option: + +`'mauricerenck.podcaster.sanitize' => true,` + +I highly recommend not doing this when there are a lot of people active on your site as it may take quite some time and blocks the database. If you can, do with a local copy and update the production database later on. + +**Make sure to disable the sanitize option after the migration!** + +## Migrating content +I tried not to interfere with existing fields whenever I could. But there are some changes to be aware of: + +The field `podcasterExplizit` is now named `podcasterExplicit` + +The episode mp3 and the cover file are now fields with the type `files` and not sections anymore. It's recommended to transfer your content (by selecting the files), but it's not necessary. + +Switching to the newest version of the PodLove player change its configuration completely, none of the old fields are present anymore. Please check [this docs](player.md) to learn how to set it up. + +The episode tab blueprint has been changed to `tabs/podcaster/episode`. The old version `tabs/podcasterepisode` is still there for backwards compatibility, but if you can, change it. + +## Feed +The feed template is built in way more modular way. It uses snippets and cleaned up internal functions and classes. If you customized the feed-template, make sure to adapt your changes to the new structure. + +## Player snippets + +If you use one of the player snippets directly, you can throw away the `feed` option. + diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 0000000..b4382b0 --- /dev/null +++ b/docs/options.md @@ -0,0 +1,2 @@ +# Options + diff --git a/docs/player.md b/docs/player.md new file mode 100644 index 0000000..d8d67c9 --- /dev/null +++ b/docs/player.md @@ -0,0 +1,52 @@ +# Setting up the Webplayer + +To embed a player into your site you can use a simple snippet coming with the Podcaster plugin: + +``` + $page]); ?> +``` + +The rest of the setup can be done in the panel. + +## Player Setup + +Podcaster comes with two types of players: + +1. A simple HTML5 audio player +2. The Podlove player + +The HTML5 player does not have any options to configure. Simply choose it as your preferred player, the snippet above will do the rest. + +### Podlove player + +The [PodLove player](https://podlove.org/podlove-web-player/) is a mighty one and allows you to configure it in detail. + +#### Colors and fonts +You can define colors and fonts to make the player match your design. Simply add an entry for the color or font, choose an option and add fill in the fields. + +![Font settings](assets/podlove-fonts.png) + +#### Active tab +You can define a tab to be opened by default. Simply select to tab you want to be opened from the select field. + +#### Clients +When users click on the subscribe button of the player, you can define, which services should be listed. There is huge list of those services, simply select the one you want to add. + +There are some services which need some additional information you have to fill in the `Service` input field. Right now those are: + +- Apple: https://podcasts.apple.com/podcast/[service] +- Derer: https://www.deezer.com/en/show/[service] +- Google Podcasts: Your feed url +- Pocket Casts: Your feed url +- Soundcloud: https://soundcloud.com/[service] +- Spotify: https://open.spotify.com/show/[service] +- Stitcher: https://www.stitcher.com/podcast/[service] +- YouTube: https://www.youtube.com/channel/[service] + +Most of the the time the `[service]` placeholder is the Id of your podcast on the platform. + +#### Sharing +You can also define which channels for sharing should be available in the sharing tab of the player. Simply select the ones you like. + +If you want to enable the user to not only share the Podcast or episode but also the current position within the episode, you can enable the `Share Playtime` feature. + diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..3a727b0 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,110 @@ +# Setup + +If you haven't already, use one of these three methods to install the plugin: + +- composer (recommended): `composer require mauricerenck/podcaster` +- zip file: download the [latest release](https://github.com/mauricerenck/podcaster/releases) unzip it, copy it to `site/plugins/podcaster` + +--- + +## Prerequisites +You’ll need a blueprint and an according template which allows you to list subpages. Have a look [here](templates.md), to see how you can get a list of all episodes for your listing. +You’ll also need a blueprint for episodes. If you have a blog, you could use the blueprint for blogposts. We will extend it later on. + +## Structure + +The first step is to decide what structure your podcast should have. There are three recommended options on how to structure your content: + +1. Seasonal structure: Every season of your podcast has its own folder. All episodes of the season are living inside of the season-folder +2. Yearly structure: Every year has its own folder. All episodes of the year are living inside of the year-folder +3. Flat structure: All episodes are living in a single folder + +Version 1 or 2 are recommended to keep things clear. + +## Panel Setup + +Login to the panel, create a new page for your podcast, let's name it "*The Podcaster*". Create a new page, name it "The Podcaster". Choose a template/blueprint allowing you to list child pages. + +### Create the feed + +- Within the page create a subpage "Feed" +- Choose the Template `Podcaster Feed` +- Fill in at least all the required fields in the `Show Details` Tab +- Switch to `RSS Settings` and enter at least all required fields + - `Podcast Id` should be a unique id for your podcast, without spaces or fancy characters, our sample podcast will have the id `the-podcaster` + - `Link` is the full URL of your podcast + - Leave `Source pages` empty for now, as we don't have any episodes yet + - Save the changes +- We leave the feed settings for now + +### Create an episode + +In order to create an episode, you need a blueprint/template for that. The podcaster plugin does not provide such a blueprint as it highly depends on your site setup and structure, but there is a *tab* you can use to extend an existing blueprint or to create a new one. **It's recommended to have a date field named `date` in your episode blueprint.** + +To add this tab to your blueprint do the following: + + tabs: + podcast: + extends: tabs/podcasterepisode + yourtabs: + ... + +If you already use tabs, simply add the podcaster episode tab. If you don't use tabs yet, please have a look at [the Kirby docs section](https://getkirby.com/docs/guide/blueprints/layout#tabs). + +Depending of the structure you've chosen, you need to create the episode directly or create a subfolder first. I'll use the *seasonal* structure, so I'll have to create a new page for the season first. This new page will have the episodes as subpages. The structure will look like so: + +- The Podcaster + - feed + - season-01 + - episode-01 + - episode-02 + - ... + - season-02 + - episode-01 + - ... + +The season pages need a template listing all its children, so does the "The Podcaster" page ([here are some tips for your templates](templates.md)). You can use a simple page blueprint for that, which is capable to list an add new subpages. + +Within your first season create your first episode. Select your episode template to do so. You should now have a new page and see a tab `Episode`. + +There are some required field: + +- The audio file +- Episode type + +Everything else can be filled but must not. Of course you should enter as much information as possible. + +**You can but should not upload a cover image here. Apple recommends to embed that cover into your mp3 ID3 data instead.** + +#### ID3 data + +When uploading an mp3 file, the plugin tries to read needed data like the duration of the episode. This data will be written to the audio’s metadata file and later used in the feed or for the player. + +In addition you can enable the option `mauricerenck.podcaster.setId3Data` which will then try to read +- the id3 title +- the id3 subtitle +- the id3 description +- the id3 chapters + +This data will then be written to the page. If you enable this feature a reload of the panel page may be required to display this information after the upload. + +If ready, publish the episode page. + +### Adding sources to the feed + +You feed will still be empty as we did not specify any sources. Head over to the feed page. Go to the `RSS Settings` and add the `season-01` page as a source. *Always add the parent folder of your episodes, not your episodes directly.* If you have multiple season, add all of them. + +When you open your the rss feed you should see the published episode. Publish your feed. You could now submit your feed to the podcast directories of your choice. + +### Kirby UUID Feature +With the latest releases came the UUID feature, which gives every file and page a unique Id. If you want to use this feature in the feed (which might be a good idea) you can enable it by setting this in your `site/config/config.php` + +``` +'mauricerenck.podcaster.feed.uuid' => true, +``` + +You should **not** set it on existing podcasts, as it changes the GUID of your episodes and this can result in duplicates on platforms like Apple Podcasts. + +## That's it + +The base setup is done. You could now start, enabling [analytics](tracking.md) or setting up the [web player](player.md). \ No newline at end of file diff --git a/docs/templates.md b/docs/templates.md new file mode 100644 index 0000000..9261675 --- /dev/null +++ b/docs/templates.md @@ -0,0 +1,16 @@ +# Tips for your templates + +To listen all the episodes of a podcast, you can use the according method of the Podcast class like so: + +```php + +getEpisodes($page) as $episode) : ?> +
  • +

    podcasterTitle(); ?>

    + podcasterDescription()->kirbytext(); ?> + Listen +
    • + +``` + +Have a look at the `podcasterfeed` template and its snippets to get some more tricks on how to handle episode data. \ No newline at end of file diff --git a/docs/tracking.md b/docs/tracking.md new file mode 100644 index 0000000..689e388 --- /dev/null +++ b/docs/tracking.md @@ -0,0 +1,56 @@ +# Tracking + +When you're running a Podcast, you would probably like to see how many people listen to your episodes. There are several ways to achieve that: + +1. Use the Podcaster Analytics (recommended) +2. Use Matomo Tracking +3. Use PodTrac + +## Setting up Podcaster Analytics + +In order to enable tracking of downloads (and other metrics). There are two ways to store tracking data: + +1. SQLite (recommended) +2. MySQL + +### Enable tracking +The first step is to enable the Podcaster Analytics feature. Open your Kirby config under `site/config/config.php` and add the following option: + +`'mauricerenck.podcaster.statsInternal' => true`, + +Next step is to configure your database. + +#### SQLite + +You have to set the `statType` to `sqlite` and you have to provide a path to where the database file should be stored. The path is relative to the root of your Kirby installation. In the example below we add it to the content folder: + +``` + 'mauricerenck.podcaster.statsInternal' => true, + 'mauricerenck.podcaster.statsType' => 'sqlite', + 'mauricerenck.podcaster.sqlitePath' => './content/', +``` + +#### MySQL + +Create a MySQL database and store the credentials to your password manager. Then add the data to your Kirby config: + +``` + 'mauricerenck.podcaster.statsHost' => 'localhost', + 'mauricerenck.podcaster.statsDatabase' => 'podcaster', + 'mauricerenck.podcaster.statsUser' => 'username', + 'mauricerenck.podcaster.statsPassword' => 'myVerySecretPassword', +``` + +##### Hint +You might want to avoid storing credentials in your PHP files, especially if you use something like git to manage your code. In this case have a look at [this plugin](https://getkirby.com/plugins/bnomei/dotenv) which will allow you to work with `.env` files. + +## Migrations +The Podcaster listens to some Kirby hooks and performs database migrations in the background. To initialize your database, simply open the Kirby Panel. This will create all the tables in your database. + +If you update the plugin in the future all needed database updates will be done in the same way. So it may be good idea to backup your database before updating the plugin. You never know… + +## Viewing analytics in the Panel + +If everything worked you should be able to see analytics in the panel. Open the Panel main menu and you should be able to see the `Podcasts`. Select the podcast you want to view, maybe try to download an episode and open the feed to see if it's working. + +Have fun! \ No newline at end of file diff --git a/index.php b/index.php index 625e292..eee6ee2 100644 --- a/index.php +++ b/index.php @@ -46,7 +46,7 @@ 'podcaster-player' => __DIR__ . '/snippets/frontend/player.php', 'podcaster-podlove-player' => __DIR__ . '/snippets/frontend/podlove-player.php', 'podcaster-html5-player' => __DIR__ . '/snippets/frontend/html5-player.php', - + 'podcaster-ogaudio' => __DIR__ . '/snippets/frontend/og-audio.php', ], 'routes' => [ @@ -58,12 +58,23 @@ $feedParent = $podcast->getPageFromSlug($slug); $feed = $feedParent->children()->filterBy('intendedTemplate', 'podcasterfeed')->first(); - if(!isset($feed)) { + if (!isset($feed)) { $this->next(); } $dbType = option('mauricerenck.podcaster.statsType', 'sqlite'); - $stats = ($dbType === 'sqlite') ? new PodcasterStatsSqlite() : new PodcasterStatsMysql(); + + switch ($dbType) { + case 'sqlite': + $stats = new PodcasterStatsSqlite(); + break; + case 'mysql': + $stats = new PodcasterStatsMysql(); + break; + default: + $stats = new PodcasterStats(); + break; + } $stats->trackFeed($feed); @@ -77,19 +88,30 @@ $podcast = new Podcast(); $dbType = option('mauricerenck.podcaster.statsType', 'sqlite'); + switch ($dbType) { + case 'sqlite': + $stats = new PodcasterStatsSqlite(); + break; + case 'mysql': + $stats = new PodcasterStatsMysql(); + break; + default: + $stats = new PodcasterStats(); + break; + } + $userAgent = $_SERVER['HTTP_USER_AGENT']; - $stats = ($dbType === 'sqlite') ? new PodcasterStatsSqlite() : new PodcasterStatsMysql(); $episode = $podcast->getPageFromSlug($slug); - if(!isset($episode)) { + if (!isset($episode)) { $this->next(); } $feed = $podcast->getFeedOfEpisode($episode); - if(!isset($feed)) { + if (!isset($feed)) { $this->next(); } @@ -104,7 +126,7 @@ 'language' => '*', 'action' => function ($lang, $episodeSlug) { $podcast = new Podcast(); - + return json_encode($podcast->getPodloveRoles($episodeSlug)); } ], @@ -113,7 +135,7 @@ 'language' => '*', 'action' => function ($lang, $episodeSlug) { $podcast = new Podcast(); - + return json_encode($podcast->getPodloveRoles($episodeSlug)); } ], @@ -124,7 +146,7 @@ $podcast = new Podcast(); $episode = $podcast->getPageFromSlug($episodeSlug); - + return json_encode($podcast->getPodloveConfigJson($episode)); } ],