saulteafarmer/castopod
1
0
Fork 0
mirror of https://code.castopod.org/adaures/castopod synced 2025-04-19 13:01:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(api): add available operations based on openapi schema

Browse Source 
use starlight-openapi plugin to generate docs

closes #536
This commit is contained in:
Yassine Doghri 2024-12-26 13:01:53 +00:00
parent 775b302f7c
commit 888d610c2d
22 changed files with 1305 additions and 1054 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.devcontainer/devcontainer.json
View File

@ -62,7 +62,8 @@
"stylelint.vscode-stylelint", "stylelint.vscode-stylelint",
"unifiedjs.vscode-mdx", "unifiedjs.vscode-mdx",
"wayou.vscode-todo-highlight", "wayou.vscode-todo-highlight",
"yzhang.markdown-all-in-one" "yzhang.markdown-all-in-one",
"42Crunch.vscode-openapi"
] ]
} }
} }

113
docs/astro.config.mjs
View File

@ -1,5 +1,6 @@
import { defineConfig } from "astro/config"; import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight"; import starlight from "@astrojs/starlight";
import starlightOpenAPI from "starlight-openapi";
import tailwind from "@astrojs/tailwind"; import tailwind from "@astrojs/tailwind";
@ -122,6 +123,16 @@ export default defineConfig({
gitlab: "https://code.castopod.org/adaures/castopod", gitlab: "https://code.castopod.org/adaures/castopod",
github: "https://github.com/ad-aures/castopod", github: "https://github.com/ad-aures/castopod",
}, },
plugins: [
starlightOpenAPI([
{
base: "en/api",
label: "API reference",
schema: "../modules/Api/Rest/V1/schema.yaml",
collapsed: true,
},
]),
],
sidebar: [ sidebar: [
{ {
label: "Introduction", label: "Introduction",
@ -193,6 +204,77 @@ export default defineConfig({
}, },
], ],
}, },
{
label: "Plugins",
badge: {
text: "Experimental",
},
items: [
{
label: "Introduction",
link: "/plugins/",
},
{
label: "Creating a plugin",
link: "/plugins/create",
},
{
label: "Reference",
items: [
{
label: "manifest.json",
link: "/plugins/manifest",
},
{
label: "hooks",
link: "/plugins/hooks",
},
],
},
],
},
// TODO: openapi plugin does not handle i18n, manual sidebar workaround
// Add the generated sidebar group to the sidebar.
// ...openAPISidebarGroups,
{
label: "API reference",
translations: {},
items: [
{
label: "Overview",
link: "/api",
},
{
label: "Operations",
items: [
{
label: "Get all podcasts",
link: "/api/operations/get-all-podcasts",
},
{
label: "Get podcast by ID",
link: "/api/operations/get-podcast-by-id",
},
{
label: "Get all episodes",
link: "/api/operations/get-all-episodes",
},
{
label: "Add a new episode",
link: "/api/operations/add-episode",
},
{
label: "Get episode by ID",
link: "/api/operations/get-episode-by-id",
},
{
label: "Publish an episode",
link: "/api/operations/publish-episode",
},
],
},
],
},
{ {
label: "User guide", label: "User guide",
translations: {}, translations: {},
@ -204,6 +286,7 @@ export default defineConfig({
{ {
label: "Manage your instance", label: "Manage your instance",
translations: {}, translations: {},
collapsed: true,
items: [ items: [
{ {
label: "Introduction", label: "Introduction",
@ -245,6 +328,7 @@ export default defineConfig({
{ {
label: "Manage your podcasts", label: "Manage your podcasts",
translations: {}, translations: {},
collapsed: true,
items: [ items: [
{ {
label: "Introduction", label: "Introduction",
@ -285,35 +369,6 @@ export default defineConfig({
}, },
], ],
}, },
{
label: "Plugins",
badge: {
text: "Experimental",
},
items: [
{
label: "Introduction",
link: "/plugins/",
},
{
label: "Creating a plugin",
link: "/plugins/create",
},
{
label: "Reference",
items: [
{
label: "manifest.json",
link: "/plugins/manifest",
},
{
label: "hooks",
link: "/plugins/hooks",
},
],
},
],
},
], ],
editLink: { editLink: {
baseUrl: "https://code.castopod.org/adaures/castopod/-/edit/main/docs/", baseUrl: "https://code.castopod.org/adaures/castopod/-/edit/main/docs/",

1
docs/package.json
View File

@ -22,6 +22,7 @@
"cssnano": "^7.0.6", "cssnano": "^7.0.6",
"postcss-preset-env": "^10.1.2", "postcss-preset-env": "^10.1.2",
"sharp": "^0.33.5", "sharp": "^0.33.5",
"starlight-openapi": "^0.9.0",
"tailwindcss": "^3.4.17", "tailwindcss": "^3.4.17",
"typescript": "^5.7.2", "typescript": "^5.7.2",
"zod": "3.24.1" "zod": "3.24.1"

249
docs/pnpm-lock.yaml generated
View File

@ -40,6 +40,9 @@ importers:
sharp: sharp:
specifier: ^0.33.5 specifier: ^0.33.5
version: 0.33.5 version: 0.33.5
starlight-openapi:
specifier: ^0.9.0
version: 0.9.0(@astrojs/markdown-remark@6.0.1)(@astrojs/starlight@0.30.3(astro@5.1.1(jiti@2.4.2)(rollup@4.29.1)(typescript@5.7.2)(yaml@2.6.1)))(openapi-types@12.1.3)
tailwindcss: tailwindcss:
specifier: ^3.4.17 specifier: ^3.4.17
version: 3.4.17 version: 3.4.17
@ -58,6 +61,12 @@ packages:
} }
engines: { node: ">=10" } engines: { node: ">=10" }
"@apidevtools/swagger-methods@3.0.2":
resolution:
{
integrity: sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==,
}
"@astrojs/check@0.9.4": "@astrojs/check@0.9.4":
resolution: resolution:
{ {
@ -162,6 +171,13 @@ packages:
integrity: sha512-GOfvSr5Nqy2z5XiwqTouBBpy5FyI6DEe+/g/Mk5am9SjILN1S5fOEvYK0GuWHg98yS/dobP4m8qyqw/URW35fQ==, integrity: sha512-GOfvSr5Nqy2z5XiwqTouBBpy5FyI6DEe+/g/Mk5am9SjILN1S5fOEvYK0GuWHg98yS/dobP4m8qyqw/URW35fQ==,
} }
"@babel/code-frame@7.26.2":
resolution:
{
integrity: sha512-RJlIHRueQgwWitWgF8OdFYGZX328Ax5BCemNGlqHfplnRT9ESi8JkFlvaVYbS+UubVY6dpv87Fs2u5M29iNFVQ==,
}
engines: { node: ">=6.9.0" }
"@babel/helper-string-parser@7.25.9": "@babel/helper-string-parser@7.25.9":
resolution: resolution:
{ {
@ -1090,6 +1106,13 @@ packages:
integrity: sha512-QyZQw03z/v1RltDPPtWxAQsYgmwbDY6CKH/YWubRY4x9UFGuAImwFYPitR2sTB/FBj0Dxf0DftoC9kqGZKWjug==, integrity: sha512-QyZQw03z/v1RltDPPtWxAQsYgmwbDY6CKH/YWubRY4x9UFGuAImwFYPitR2sTB/FBj0Dxf0DftoC9kqGZKWjug==,
} }
"@humanwhocodes/momoa@2.0.4":
resolution:
{
integrity: sha512-RE815I4arJFtt+FVeU1Tgp9/Xvecacji8w/V6XtXsWWH/wz/eNkNbhb+ny/+PlVZjV0rxQpRSQKNKE3lcktHEA==,
}
engines: { node: ">=10.10.0" }
"@img/sharp-darwin-arm64@0.33.5": "@img/sharp-darwin-arm64@0.33.5":
resolution: resolution:
{ {
@ -1292,6 +1315,12 @@ packages:
integrity: sha512-vNk6aEwybGtawWmy/PzwnGDOjCkLWSD2wqvjGGAgOAwCGWySYXfYoxt00IJkTF+8Lb57DwOb3Aa0o9CApepiYQ==, integrity: sha512-vNk6aEwybGtawWmy/PzwnGDOjCkLWSD2wqvjGGAgOAwCGWySYXfYoxt00IJkTF+8Lb57DwOb3Aa0o9CApepiYQ==,
} }
"@jsdevtools/ono@7.1.3":
resolution:
{
integrity: sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==,
}
"@mdx-js/mdx@3.1.0": "@mdx-js/mdx@3.1.0":
resolution: resolution:
{ {
@ -1511,6 +1540,37 @@ packages:
} }
engines: { node: ">=14" } engines: { node: ">=14" }
"@readme/better-ajv-errors@1.6.0":
resolution:
{
integrity: sha512-9gO9rld84Jgu13kcbKRU+WHseNhaVt76wYMeRDGsUGYxwJtI3RmEJ9LY9dZCYQGI8eUZLuxb5qDja0nqklpFjQ==,
}
engines: { node: ">=14" }
peerDependencies:
ajv: 4.11.8 - 8
"@readme/json-schema-ref-parser@1.2.0":
resolution:
{
integrity: sha512-Bt3QVovFSua4QmHa65EHUmh2xS0XJ3rgTEUPH998f4OW4VVJke3BuS16f+kM0ZLOGdvIrzrPRqwihuv5BAjtrA==,
}
"@readme/openapi-parser@2.6.0":
resolution:
{
integrity: sha512-pyFJXezWj9WI1O+gdp95CoxfY+i+Uq3kKk4zXIFuRAZi9YnHpHOpjumWWr67wkmRTw19Hskh9spyY0Iyikf3fA==,
}
engines: { node: ">=18" }
peerDependencies:
openapi-types: ">=7"
"@readme/openapi-schemas@3.1.0":
resolution:
{
integrity: sha512-9FC/6ho8uFa8fV50+FPy/ngWN53jaUu4GRXlAjcxIRrzhltJnpKkBG2Tp0IDraFJeWrOpk84RJ9EMEEYzaI1Bw==,
}
engines: { node: ">=18" }
"@rollup/pluginutils@5.1.4": "@rollup/pluginutils@5.1.4":
resolution: resolution:
{ {
@ -1754,6 +1814,12 @@ packages:
integrity: sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==, integrity: sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==,
} }
"@types/json-schema@7.0.15":
resolution:
{
integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==,
}
"@types/mdast@4.0.4": "@types/mdast@4.0.4":
resolution: resolution:
{ {
@ -1874,6 +1940,17 @@ packages:
engines: { node: ">=0.4.0" } engines: { node: ">=0.4.0" }
hasBin: true hasBin: true
ajv-draft-04@1.0.0:
resolution:
{
integrity: sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==,
}
peerDependencies:
ajv: ^8.5.0
peerDependenciesMeta:
ajv:
optional: true
ajv@8.17.1: ajv@8.17.1:
resolution: resolution:
{ {
@ -2070,6 +2147,12 @@ packages:
engines: { node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7 } engines: { node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7 }
hasBin: true hasBin: true
call-me-maybe@1.0.2:
resolution:
{
integrity: sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==,
}
camelcase-css@2.0.1: camelcase-css@2.0.1:
resolution: resolution:
{ {
@ -2102,6 +2185,13 @@ packages:
integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==, integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==,
} }
chalk@4.1.2:
resolution:
{
integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==,
}
engines: { node: ">=10" }
chalk@5.4.1: chalk@5.4.1:
resolution: resolution:
{ {
@ -2188,6 +2278,13 @@ packages:
} }
engines: { node: ">=6" } engines: { node: ">=6" }
code-error-fragment@0.0.230:
resolution:
{
integrity: sha512-cadkfKp6932H8UkhzE/gcUqhRMNf8jHzkAN7+5Myabswaghu4xABTgPHDCjW+dBAJxj/SpkTYokpzDqY4pCzQw==,
}
engines: { node: ">= 4" }
collapse-white-space@2.1.0: collapse-white-space@2.1.0:
resolution: resolution:
{ {
@ -2861,12 +2958,25 @@ packages:
integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==, integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==,
} }
grapheme-splitter@1.0.4:
resolution:
{
integrity: sha512-bzh50DW9kTPM00T8y4o8vQg89Di9oLJVLW/KaOGIXJWP/iqCN6WKYkbNOF04vFLJhwcpYUh9ydh/+5vpOqV4YQ==,
}
h3@1.13.0: h3@1.13.0:
resolution: resolution:
{ {
integrity: sha512-vFEAu/yf8UMUcB4s43OaDaigcqpQd14yanmOsn+NcRX3/guSKncyE2rOYhq8RIchgJrPSs/QiIddnTTR1ddiAg==, integrity: sha512-vFEAu/yf8UMUcB4s43OaDaigcqpQd14yanmOsn+NcRX3/guSKncyE2rOYhq8RIchgJrPSs/QiIddnTTR1ddiAg==,
} }
has-flag@4.0.0:
resolution:
{
integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==,
}
engines: { node: ">=8" }
hasown@2.0.2: hasown@2.0.2:
resolution: resolution:
{ {
@ -3204,6 +3314,12 @@ packages:
} }
hasBin: true hasBin: true
js-tokens@4.0.0:
resolution:
{
integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==,
}
js-yaml@3.14.1: js-yaml@3.14.1:
resolution: resolution:
{ {
@ -3224,6 +3340,13 @@ packages:
integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==, integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==,
} }
json-to-ast@2.1.0:
resolution:
{
integrity: sha512-W9Lq347r8tA1DfMvAGn9QNcgYm4Wm7Yc+k8e6vezpMnRT+NHbtlxgNBXRVjXe9YM6eTn6+p/MKOlV/aABJcSnQ==,
}
engines: { node: ">= 4" }
jsonc-parser@2.3.1: jsonc-parser@2.3.1:
resolution: resolution:
{ {
@ -3236,6 +3359,13 @@ packages:
integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==, integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==,
} }
jsonpointer@5.0.1:
resolution:
{
integrity: sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ==,
}
engines: { node: ">=0.10.0" }
kleur@3.0.3: kleur@3.0.3:
resolution: resolution:
{ {
@ -3250,6 +3380,13 @@ packages:
} }
engines: { node: ">=6" } engines: { node: ">=6" }
leven@3.1.0:
resolution:
{
integrity: sha512-qsda+H8jTaUaN/x5vzW2rzc+8Rw4TAQ/4KjB46IwK5VH+IlVeeeje/EoZRpiXvIqjFgK84QffqPztGI3VBLG1A==,
}
engines: { node: ">=6" }
lilconfig@3.1.3: lilconfig@3.1.3:
resolution: resolution:
{ {
@ -3867,6 +4004,12 @@ packages:
integrity: sha512-dekySTEvCxCj0IgKcA2uUCO/e4ArsqpucDPcX26w9ajx+DvMWLc5eZeJaRQkd7oC/+rwif5gnT900tA34uN9Zw==, integrity: sha512-dekySTEvCxCj0IgKcA2uUCO/e4ArsqpucDPcX26w9ajx+DvMWLc5eZeJaRQkd7oC/+rwif5gnT900tA34uN9Zw==,
} }
openapi-types@12.1.3:
resolution:
{
integrity: sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==,
}
p-limit@2.3.0: p-limit@2.3.0:
resolution: resolution:
{ {
@ -4956,6 +5099,16 @@ packages:
integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==, integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==,
} }
starlight-openapi@0.9.0:
resolution:
{
integrity: sha512-YKsYNqYhWu3VF91z4XB1os4ZXwTsgz1LCZggeK/G6RguV4hcaFH18wHYGtO9icqPR+ZbJyrLAdlAjF3CvGBAWA==,
}
engines: { node: ">=18.17.1" }
peerDependencies:
"@astrojs/markdown-remark": ">=6.0.0"
"@astrojs/starlight": ">=0.30.0"
std-env@3.8.0: std-env@3.8.0:
resolution: resolution:
{ {
@ -5052,6 +5205,13 @@ packages:
engines: { node: ">=16 || 14 >=14.17" } engines: { node: ">=16 || 14 >=14.17" }
hasBin: true hasBin: true
supports-color@7.2.0:
resolution:
{
integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==,
}
engines: { node: ">=8" }
supports-preserve-symlinks-flag@1.0.0: supports-preserve-symlinks-flag@1.0.0:
resolution: resolution:
{ {
@ -5751,6 +5911,8 @@ packages:
snapshots: snapshots:
"@alloc/quick-lru@5.2.0": {} "@alloc/quick-lru@5.2.0": {}
"@apidevtools/swagger-methods@3.0.2": {}
"@astrojs/check@0.9.4(typescript@5.7.2)": "@astrojs/check@0.9.4(typescript@5.7.2)":
dependencies: dependencies:
"@astrojs/language-server": 2.15.4(typescript@5.7.2) "@astrojs/language-server": 2.15.4(typescript@5.7.2)
@ -5904,6 +6066,12 @@ snapshots:
dependencies: dependencies:
yaml: 2.6.1 yaml: 2.6.1
"@babel/code-frame@7.26.2":
dependencies:
"@babel/helper-validator-identifier": 7.25.9
js-tokens: 4.0.0
picocolors: 1.1.1
"@babel/helper-string-parser@7.25.9": {} "@babel/helper-string-parser@7.25.9": {}
"@babel/helper-validator-identifier@7.25.9": {} "@babel/helper-validator-identifier@7.25.9": {}
@ -6373,6 +6541,8 @@ snapshots:
"@fontsource/rubik@5.1.0": {} "@fontsource/rubik@5.1.0": {}
"@humanwhocodes/momoa@2.0.4": {}
"@img/sharp-darwin-arm64@0.33.5": "@img/sharp-darwin-arm64@0.33.5":
optionalDependencies: optionalDependencies:
"@img/sharp-libvips-darwin-arm64": 1.0.4 "@img/sharp-libvips-darwin-arm64": 1.0.4
@ -6474,6 +6644,8 @@ snapshots:
"@jridgewell/resolve-uri": 3.1.2 "@jridgewell/resolve-uri": 3.1.2
"@jridgewell/sourcemap-codec": 1.5.0 "@jridgewell/sourcemap-codec": 1.5.0
"@jsdevtools/ono@7.1.3": {}
"@mdx-js/mdx@3.1.0(acorn@8.14.0)": "@mdx-js/mdx@3.1.0(acorn@8.14.0)":
dependencies: dependencies:
"@types/estree": 1.0.6 "@types/estree": 1.0.6
@ -6603,6 +6775,38 @@ snapshots:
"@pkgjs/parseargs@0.11.0": "@pkgjs/parseargs@0.11.0":
optional: true optional: true
"@readme/better-ajv-errors@1.6.0(ajv@8.17.1)":
dependencies:
"@babel/code-frame": 7.26.2
"@babel/runtime": 7.26.0
"@humanwhocodes/momoa": 2.0.4
ajv: 8.17.1
chalk: 4.1.2
json-to-ast: 2.1.0
jsonpointer: 5.0.1
leven: 3.1.0
"@readme/json-schema-ref-parser@1.2.0":
dependencies:
"@jsdevtools/ono": 7.1.3
"@types/json-schema": 7.0.15
call-me-maybe: 1.0.2
js-yaml: 4.1.0
"@readme/openapi-parser@2.6.0(openapi-types@12.1.3)":
dependencies:
"@apidevtools/swagger-methods": 3.0.2
"@jsdevtools/ono": 7.1.3
"@readme/better-ajv-errors": 1.6.0(ajv@8.17.1)
"@readme/json-schema-ref-parser": 1.2.0
"@readme/openapi-schemas": 3.1.0
ajv: 8.17.1
ajv-draft-04: 1.0.0(ajv@8.17.1)
call-me-maybe: 1.0.2
openapi-types: 12.1.3
"@readme/openapi-schemas@3.1.0": {}
"@rollup/pluginutils@5.1.4(rollup@4.29.1)": "@rollup/pluginutils@5.1.4(rollup@4.29.1)":
dependencies: dependencies:
"@types/estree": 1.0.6 "@types/estree": 1.0.6
@ -6719,6 +6923,8 @@ snapshots:
"@types/js-yaml@4.0.9": {} "@types/js-yaml@4.0.9": {}
"@types/json-schema@7.0.15": {}
"@types/mdast@4.0.4": "@types/mdast@4.0.4":
dependencies: dependencies:
"@types/unist": 3.0.3 "@types/unist": 3.0.3
@ -6799,6 +7005,10 @@ snapshots:
acorn@8.14.0: {} acorn@8.14.0: {}
ajv-draft-04@1.0.0(ajv@8.17.1):
optionalDependencies:
ajv: 8.17.1
ajv@8.17.1: ajv@8.17.1:
dependencies: dependencies:
fast-deep-equal: 3.1.3 fast-deep-equal: 3.1.3
@ -6999,6 +7209,8 @@ snapshots:
node-releases: 2.0.19 node-releases: 2.0.19
update-browserslist-db: 1.1.1(browserslist@4.24.3) update-browserslist-db: 1.1.1(browserslist@4.24.3)
call-me-maybe@1.0.2: {}
camelcase-css@2.0.1: {} camelcase-css@2.0.1: {}
camelcase@8.0.0: {} camelcase@8.0.0: {}
@ -7014,6 +7226,11 @@ snapshots:
ccount@2.0.1: {} ccount@2.0.1: {}
chalk@4.1.2:
dependencies:
ansi-styles: 4.3.0
supports-color: 7.2.0
chalk@5.4.1: {} chalk@5.4.1: {}
character-entities-html4@2.1.0: {} character-entities-html4@2.1.0: {}
@ -7062,6 +7279,8 @@ snapshots:
clsx@2.1.1: {} clsx@2.1.1: {}
code-error-fragment@0.0.230: {}
collapse-white-space@2.1.0: {} collapse-white-space@2.1.0: {}
color-convert@2.0.1: color-convert@2.0.1:
@ -7485,6 +7704,8 @@ snapshots:
graceful-fs@4.2.11: {} graceful-fs@4.2.11: {}
grapheme-splitter@1.0.4: {}
h3@1.13.0: h3@1.13.0:
dependencies: dependencies:
cookie-es: 1.2.2 cookie-es: 1.2.2
@ -7498,6 +7719,8 @@ snapshots:
uncrypto: 0.1.3 uncrypto: 0.1.3
unenv: 1.10.0 unenv: 1.10.0
has-flag@4.0.0: {}
hasown@2.0.2: hasown@2.0.2:
dependencies: dependencies:
function-bind: 1.1.2 function-bind: 1.1.2
@ -7776,6 +7999,8 @@ snapshots:
jiti@2.4.2: {} jiti@2.4.2: {}
js-tokens@4.0.0: {}
js-yaml@3.14.1: js-yaml@3.14.1:
dependencies: dependencies:
argparse: 1.0.10 argparse: 1.0.10
@ -7787,14 +8012,23 @@ snapshots:
json-schema-traverse@1.0.0: {} json-schema-traverse@1.0.0: {}
json-to-ast@2.1.0:
dependencies:
code-error-fragment: 0.0.230
grapheme-splitter: 1.0.4
jsonc-parser@2.3.1: {} jsonc-parser@2.3.1: {}
jsonc-parser@3.3.1: {} jsonc-parser@3.3.1: {}
jsonpointer@5.0.1: {}
kleur@3.0.3: {} kleur@3.0.3: {}
kleur@4.1.5: {} kleur@4.1.5: {}
leven@3.1.0: {}
lilconfig@3.1.3: {} lilconfig@3.1.3: {}
lines-and-columns@1.2.4: {} lines-and-columns@1.2.4: {}
@ -8405,6 +8639,8 @@ snapshots:
regex: 5.0.2 regex: 5.0.2
regex-recursion: 5.0.0 regex-recursion: 5.0.0
openapi-types@12.1.3: {}
p-limit@2.3.0: p-limit@2.3.0:
dependencies: dependencies:
p-try: 2.2.0 p-try: 2.2.0
@ -9212,6 +9448,15 @@ snapshots:
sprintf-js@1.0.3: {} sprintf-js@1.0.3: {}
starlight-openapi@0.9.0(@astrojs/markdown-remark@6.0.1)(@astrojs/starlight@0.30.3(astro@5.1.1(jiti@2.4.2)(rollup@4.29.1)(typescript@5.7.2)(yaml@2.6.1)))(openapi-types@12.1.3):
dependencies:
"@astrojs/markdown-remark": 6.0.1
"@astrojs/starlight": 0.30.3(astro@5.1.1(jiti@2.4.2)(rollup@4.29.1)(typescript@5.7.2)(yaml@2.6.1))
"@readme/openapi-parser": 2.6.0(openapi-types@12.1.3)
github-slugger: 2.0.0
transitivePeerDependencies:
- openapi-types
std-env@3.8.0: {} std-env@3.8.0: {}
stream-replace-string@2.0.0: {} stream-replace-string@2.0.0: {}
@ -9275,6 +9520,10 @@ snapshots:
pirates: 4.0.6 pirates: 4.0.6
ts-interface-checker: 0.1.13 ts-interface-checker: 0.1.13
supports-color@7.2.0:
dependencies:
has-flag: 4.0.0
supports-preserve-symlinks-flag@1.0.0: {} supports-preserve-symlinks-flag@1.0.0: {}
svgo@3.3.2: svgo@3.3.2:

82
docs/src/content/docs/en/getting-started/create-episode.mdx
View File

@ -2,33 +2,37 @@
title: Create your first episode title: Create your first episode
--- ---
To add an episode to your podcast, choose Podcasts -> All podcasts from your instance management left hand sidebar. To add an episode to your podcast, choose Podcasts -> All podcasts from your
Then choose Podcast dashboard and press the Add an episode button in the upper right hand corner and fill out the instance management left hand sidebar. Then choose Podcast dashboard and press
the Add an episode button in the upper right hand corner and fill out the
following fields. following fields.
## Episode Info ## Episode Info
### Audio file ### Audio file
Press the `Choose File` button to select the audio file to upload to Castopod. The audio file must be an mp3 or m4a Press the `Choose File` button to select the audio file to upload to Castopod.
file and cannot be larger than 512 megabytes. The audio file must be an mp3 or m4a file and cannot be larger than 512
megabytes.
### Episode cover ### Episode cover
You can optionally add a different podcast cover / artwork. Press `Choose File` and select an image from your computer You can optionally add a different podcast cover / artwork. Press `Choose File`
that must be at least 1400px wide and tall and no larger than 3000px wide and tall. If you do not choose an and select an image from your computer that must be at least 1400px wide and
episode cover, your default podcast artwork will be used. tall and no larger than 3000px wide and tall. If you do not choose an episode
cover, your default podcast artwork will be used.
### Title ### Title
Enter the name for your new episode. Do not add the season or episode number in the **Title** field. Choose a clear Enter the name for your new episode. Do not add the season or episode number in
and concise episode name to help your listeners. the **Title** field. Choose a clear and concise episode name to help your
listeners.
### Permalink ### Permalink
The permalink is the link to the public episode page. This will be automatically filled out based on the title The permalink is the link to the public episode page. This will be automatically
you entered above. If you wish to have a different permalink, press the edit button to the right of the filled out based on the title you entered above. If you wish to have a different
displayed permalink. permalink, press the edit button to the right of the displayed permalink.
### Season and Episode ### Season and Episode
@ -36,46 +40,54 @@ You can optionally add a season and / or episode number to your episode.
## Show Notes ## Show Notes
Describe your episode in detail. You can use up to 4000 characters, and you can use Markdown to style your show Describe your episode in detail. You can use up to 4000 characters, and you can
notes. You can expand the text box by pressing and holding the bottom right corner of the text box. use Markdown to style your show notes. You can expand the text box by pressing
and holding the bottom right corner of the text box.
When your show notes are complete, press `Preview` to view how your show notes will be displayed. When your show notes are complete, press `Preview` to view how your show notes
will be displayed.
## Additional Files ## Additional Files
### Transcripts ### Transcripts
You can add a transcript to your episode by choosing a file in SRT or VTT format to upload. Transcripts will be You can add a transcript to your episode by choosing a file in SRT or VTT format
shown in a tab on the episode page and some podcast apps such as Apple Podcasts can display the transcript. to upload. Transcripts will be shown in a tab on the episode page and some
Transcripts help users who may have a hearing disability and can also help with search engine optimization. podcast apps such as Apple Podcasts can display the transcript.
Transcripts help users who may have a hearing disability and can also help with
search engine optimization.
### Chapters ### Chapters
You can optionally upload a chapters file in JSON format. To learn more about chapters and for an example of the You can optionally upload a chapters file in JSON format. To learn more about
correct format, visit the [Podcast Namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md). chapters and for an example of the correct format, visit the
[Podcast Namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md).
!!! note !!! note Not all podcast players natively support chapters in JSON format. More
Not all podcast players natively support chapters in JSON format. More modern players, such as Fountain and modern players, such as Fountain and Apple Podcasts, do support chapters in JSON
Apple Podcasts, do support chapters in JSON format. format.
## Publish your episode ## Publish your episode
When complete, press the `Create episode` button at the bottom of the page. You will be automatically directed to When complete, press the `Create episode` button at the bottom of the page. You
the next step to publish your episode. Your episode is in draft mode and is not yet published. You can preview will be automatically directed to the next step to publish your episode. Your
how your episode will look when published or publish your episode. To publish your episode, press the `Publish` button episode is in draft mode and is not yet published. You can preview how your
in the upper right hand corner. episode will look when published or publish your episode. To publish your
episode, press the `Publish` button in the upper right hand corner.
### Create your announcement post ### Create your announcement post
After pressing `Publish` you will be directed to the next page to draft your announcement post. Write your message After pressing `Publish` you will be directed to the next page to draft your
in the text box provided. This will be the message broadcast to the Fediverse and published on your podcast's home announcement post. Write your message in the text box provided. This will be the
page. message broadcast to the Fediverse and published on your podcast's home page.
### Publication date ### Publication date
Choose `Now` or `Schedule` to publish your episode. If you choose `Now`, your episode will be live. Or you can Choose `Now` or `Schedule` to publish your episode. If you choose `Now`, your
schedule the day and time to publish your episode by choosing the `Schedule` radio button and choosing the day and episode will be live. Or you can schedule the day and time to publish your
time. Press `Publish` to finish. episode by choosing the `Schedule` radio button and choosing the day and time.
Press `Publish` to finish.
Your RSS feed will be automatically updated with your episode information and listeners who subscribe will be Your RSS feed will be automatically updated with your episode information and
notified of a new episode. Congratulations on publishing your first episode! listeners who subscribe will be notified of a new episode. Congratulations on
publishing your first episode!

89
docs/src/content/docs/en/getting-started/create-podcast.mdx
View File

@ -4,15 +4,16 @@ title: Create your first podcast
import { Aside } from "@astrojs/starlight/components"; import { Aside } from "@astrojs/starlight/components";
From the left hand navigation sidebar, press the `+` sign to the right of Podcasts to create your first podcast. From the left hand navigation sidebar, press the `+` sign to the right of
Podcasts to create your first podcast.
## Podcast Identity ## Podcast Identity
### Podcast Cover ### Podcast Cover
To upload your podcast cover art, press the `Choose File` button and choose your cover art from your computer. The To upload your podcast cover art, press the `Choose File` button and choose your
cover art needs to be in JPG or PNG format and a minimum of 1400px wide and tall with a maximum of 3000px wide and cover art from your computer. The cover art needs to be in JPG or PNG format and
tall. a minimum of 1400px wide and tall with a maximum of 3000px wide and tall.
### Title ### Title
@ -20,13 +21,15 @@ Enter the name of your podcast in the **Title** field.
### Description ### Description
Describe what your podcast is about. You can use Markdown to style the text and you can resize the text box by Describe what your podcast is about. You can use Markdown to style the text and
pressing and holding the bottom right hand corner of the text box. you can resize the text box by pressing and holding the bottom right hand corner
of the text box.
### Type ### Type
Choose how your listeners should listen to your podcast. **Episodic** lets listeners know they can consume your podcast Choose how your listeners should listen to your podcast. **Episodic** lets
in any order, such as an interview podcast. Choose **Serial** if your episodes are meant to be listened to in listeners know they can consume your podcast in any order, such as an interview
podcast. Choose **Serial** if your episodes are meant to be listened to in
sequential order. sequential order.
### Medium ### Medium
@ -34,8 +37,10 @@ sequential order.
Choose the type of audio for your podcast: Choose the type of audio for your podcast:
- **Podcast**: a standard podcast. - **Podcast**: a standard podcast.
- **Music**: A feed of music organized into an "album" with each item a song within the album. - **Music**: A feed of music organized into an "album" with each item a song
- **Audiobook**: A specific type of audio with one item per feed, or where items represent chapters within a book. within the album.
- **Audiobook**: A specific type of audio with one item per feed, or where items
represent chapters within a book.
## Classification ## Classification
@ -45,7 +50,8 @@ From the dropdown menu, choose which language is spoken in your podcast.
### Category ### Category
Choose the category that represents your podcast, such as Arts, Comedy, Sports, Technology, etc. Choose the category that represents your podcast, such as Arts, Comedy, Sports,
Technology, etc.
### Other categories (optional) ### Other categories (optional)
@ -53,21 +59,25 @@ You can choose a second category in addition to the main category you set up.
### Parental advisory ### Parental advisory
Choose if your podcast has explicit content or swearing or choose Clean if your podcast is suitable for everyone. You Choose if your podcast has explicit content or swearing or choose Clean if your
can also choose to leave this category as undefined. When [creating a new episode](../podcast/episodes), podcast is suitable for everyone. You can also choose to leave this category as
you will also have the opportunity to choose clean, explicit, or undefined on a per episode basis. undefined. When [creating a new episode](../podcast/episodes), you will also
have the opportunity to choose clean, explicit, or undefined on a per episode
basis.
## Author ## Author
### Owner name and email ### Owner name and email
Enter the owner name and email in the provided fields. This is only visible in the RSS feed and is used by other Enter the owner name and email in the provided fields. This is only visible in
podcasting platforms to verify your ownership of your podcast. You can choose to remove the owner email the RSS feed and is used by other podcasting platforms to verify your ownership
from the public RSS feed by using the provided toggle. of your podcast. You can choose to remove the owner email from the public RSS
feed by using the provided toggle.
### Publisher ### Publisher
If your podcast is part of a podcast network or is produced by a company, enter the publisher here. If your podcast is part of a podcast network or is produced by a company, enter
the publisher here.
### Copyright ### Copyright
@ -75,40 +85,47 @@ You can optionally add the copyright holder in this field.
### Fediverse identity ### Fediverse identity
Enter the handle (or nickname) for your podcast. This will allow people on Mastodon and other Fediverse services Enter the handle (or nickname) for your podcast. This will allow people on
to follow your podcast. Your handle will be shown as @yourdomain.com@handle on the Fediverse. Mastodon and other Fediverse services to follow your podcast. Your handle will
be shown as @yourdomain.com@handle on the Fediverse.
To learn more about Fediverse integration, visit the [Fediverse documentation page](../instance/fediverse). To learn more about Fediverse integration, visit the
[Fediverse documentation page](../instance/fediverse).
### Podcast banner ### Podcast banner
Upload a banner image to be displayed at the top of your podcast's home page. The banner must have a 3:1 ration and Upload a banner image to be displayed at the top of your podcast's home page.
be at least 1500px wide. The banner must have a 3:1 ration and be at least 1500px wide.
### Premium ### Premium
Toggle this setting to set all episodes by default as premium. When creating an episode, it will default to premium, Toggle this setting to set all episodes by default as premium. When creating an
and you can still choose to make some episodes, trailers, or bonus content as free and public. episode, it will default to premium, and you can still choose to make some
episodes, trailers, or bonus content as free and public.
## Open Podcast Prefix Project (OP3) ## Open Podcast Prefix Project (OP3)
The [Open Podcast Prefix Project](https://op3.dev) is an open source and trusted third party analytics service. If The [Open Podcast Prefix Project](https://op3.dev) is an open source and trusted
you toggle this to enabled, you will be able to view analytics for your podcast over time including the number of third party analytics service. If you toggle this to enabled, you will be able
listens over time, episode comparison charts, and more. to view analytics for your podcast over time including the number of listens
over time, episode comparison charts, and more.
## Location ## Location
You can optionally add a real or fictitious location name in this field. When You can optionally add a real or fictitious location name in this field. When
[creating a new episode](../podcast/episodes) you also can add a location to an individual episode. [creating a new episode](../podcast/episodes) you also can add a location to an
individual episode.
## Advanced Parameters ## Advanced Parameters
You can optionally toggle the following settings: You can optionally toggle the following settings:
- **Prevent podcast from being copied**: this locks your podcast and does not allow other podcast platforms to import - **Prevent podcast from being copied**: this locks your podcast and does not
your podcast. If you decide in the future to migrate away from Castopod to a new platform, this toggle will need to be allow other podcast platforms to import your podcast. If you decide in the
unchecked. future to migrate away from Castopod to a new platform, this toggle will need
- **Podcast should be hidden from public catalogues**: If toggled, a best effort is made to hide the entire podcast from to be unchecked.
appearing in Apple Podcasts, YouTube Music, and any other third party podcast apps. (Not guaranteed) - **Podcast should be hidden from public catalogues**: If toggled, a best effort
- **Podcast will not be having new episodes**: If your podcast comes to an end, you can toggle this to let listeners is made to hide the entire podcast from appearing in Apple Podcasts, YouTube
know there will not be new episodes. Music, and any other third party podcast apps. (Not guaranteed)
- **Podcast will not be having new episodes**: If your podcast comes to an end,
you can toggle this to let listeners know there will not be new episodes.

35
docs/src/content/docs/en/user-guide/instance/fediverse.mdx
View File

@ -6,30 +6,35 @@ title: Fediverse
Wikipedia defines the Fediverse as: Wikipedia defines the Fediverse as:
> The fediverse is a collection of social networking services that can communicate with each other using a common > The fediverse is a collection of social networking services that can
> protocol, ActivityPub. Users of different websites can send and receive status updates, multimedia files and other > communicate with each other using a common protocol, ActivityPub. Users of
> data across the network. > different websites can send and receive status updates, multimedia files and
> other data across the network.
Your podcast is connected to the Fediverse and, for example, Mastodon users can subscribe to your handle and will Your podcast is connected to the Fediverse and, for example, Mastodon users can
receive a message every time your podcast publishes a new episode. You can also broadcast messages to your followers subscribe to your handle and will receive a message every time your podcast
on the Fediverse from your [home page](../website#home). Mastodon users can like and share your posts. publishes a new episode. You can also broadcast messages to your followers on
the Fediverse from your [home page](../website#home). Mastodon users can like
and share your posts.
## Manage Fediverse Blocks ## Manage Fediverse Blocks
You can block a Fediverse user or an entire domain to help stop harassment or spam. You can block a Fediverse user or an entire domain to help stop harassment or
spam.
### Blocked Accounts ### Blocked Accounts
To block a specific Fediverse user, enter the user's handle in the **Account Handle** text box. It should be in To block a specific Fediverse user, enter the user's handle in the **Account
the format of `@user@domain.com`. Press `Block` to block the user from following your podcast. Handle** text box. It should be in the format of `@user@domain.com`. Press
`Block` to block the user from following your podcast.
A list of all blocked accounts is shown below the **Account Handle** text box. You can choose to unblock a user A list of all blocked accounts is shown below the **Account Handle** text box.
by pressing the `Unblock` button. You can choose to unblock a user by pressing the `Unblock` button.
### Blocked Domains ### Blocked Domains
To block an entire domain, enter the domain name such as `www.example.com` in the **Domain Name** field and press To block an entire domain, enter the domain name such as `www.example.com` in
`Block`. the **Domain Name** field and press `Block`.
A list of all blocked domains is shown below the **Domain Name** text box. You can choose to unblock a domain A list of all blocked domains is shown below the **Domain Name** text box. You
by pressing the `Unblock` button. can choose to unblock a domain by pressing the `Unblock` button.

12
docs/src/content/docs/en/user-guide/instance/index.mdx
View File

@ -6,15 +6,17 @@ import { LinkCard, CardGrid } from "@astrojs/starlight/components";
## What is an instance? ## What is an instance?
Your podcast is hosted on your sever and connected to the [Fediverse](fediverse) in what is called an _instance_. Your podcast is hosted on your sever and connected to the [Fediverse](fediverse)
Your instance can manage multiple podcasts, people and users, and host additional pages found on all of your podcasts. in what is called an _instance_. Your instance can manage multiple podcasts,
people and users, and host additional pages found on all of your podcasts.
Managing your instance, including podcasts, people, and users is separate from the settings for each Managing your instance, including podcasts, people, and users is separate from
individual podcast. the settings for each individual podcast.
## Ready to get started? ## Ready to get started?
Learn more about adding podcasts, users, and more by clicking one of the links below. Learn more about adding podcasts, users, and more by clicking one of the links
below.
<CardGrid> <CardGrid>
<LinkCard title="Create or import a podcast" href="podcast" /> <LinkCard title="Create or import a podcast" href="podcast" />

19
docs/src/content/docs/en/user-guide/instance/pages.mdx
View File

@ -4,8 +4,8 @@ title: Pages
## Add Pages ## Add Pages
You can add static pages linked from your podcast's home page. From the left hand navigation, choose the `+` sign or You can add static pages linked from your podcast's home page. From the left
click `Pages` -> `New Page`. hand navigation, choose the `+` sign or click `Pages` -> `New Page`.
### Title ### Title
@ -13,16 +13,19 @@ In the **Title** text box, enter the name for the page you are adding.
### Permalink ### Permalink
In the `Permalink` text box, enter the permalink if you want it different than the title. In the `Permalink` text box, enter the permalink if you want it different than
the title.
### Content ### Content
You can add your page content in the **Content** text box. You can use Markdown to style your text. You can add your page content in the **Content** text box. You can use Markdown
to style your text.
When finished, press the `Create page` button. You can view your page from your podcast's home page. It will be When finished, press the `Create page` button. You can view your page from your
linked in the right hand side bar navigation. podcast's home page. It will be linked in the right hand side bar navigation.
## Delete or Edit a Page ## Delete or Edit a Page
After adding a page, you can delete the page or edit it by choosing `Pages` -> `All Pages` from the instance After adding a page, you can delete the page or edit it by choosing `Pages` ->
navigation sidebar on the left. Press the corresponding button to view the page, edit it, or delete it. `All Pages` from the instance navigation sidebar on the left. Press the
corresponding button to view the page, edit it, or delete it.

27
docs/src/content/docs/en/user-guide/instance/persons.mdx
View File

@ -2,21 +2,24 @@
title: Manage Podcast contributors title: Manage Podcast contributors
--- ---
The **Persons** section allows you to add podcast contributors. It is needed in the Podcast section to assign The **Persons** section allows you to add podcast contributors. It is needed in
roles and is also used on the **Credits** page linked from your podcast's homepage. the Podcast section to assign roles and is also used on the **Credits** page
linked from your podcast's homepage.
From the left hand navigation, press `Persons` to expand the menu. To view a list of all people that have been From the left hand navigation, press `Persons` to expand the menu. To view a
added to Castopod, press `All Persons`. list of all people that have been added to Castopod, press `All Persons`.
## Add a person ## Add a person
To add a person, press `New Person` from the left hand sidebar or press `Create a person` from the upper right hand To add a person, press `New Person` from the left hand sidebar or press
corner of the **All Persons** page and fill out the following fields: `Create a person` from the upper right hand corner of the **All Persons** page
and fill out the following fields:
- **Avatar**: You can optionally add a picture or avatar of the person. Press `Choose File` and upload a picture - **Avatar**: You can optionally add a picture or avatar of the person. Press
from your computer. It must be at least 400px wide and tall. `Choose File` and upload a picture from your computer. It must be at least
400px wide and tall.
- **Full Name**: Enter the name as you want it displayed on your website. - **Full Name**: Enter the name as you want it displayed on your website.
- **Unique Name**: Enter a unique username for the person you are adding. This will be displayed in the Podcasts - **Unique Name**: Enter a unique username for the person you are adding. This
secton when assigning this person a role. will be displayed in the Podcasts secton when assigning this person a role.
- **Information URL**: Enter a URL for the person's homepage, profile, or social media account to be linked from the - **Information URL**: Enter a URL for the person's homepage, profile, or social
[Credits page](../website/credits). media account to be linked from the [Credits page](../website/credits).

128
docs/src/content/docs/en/user-guide/instance/podcast.mdx
View File

@ -2,19 +2,21 @@
title: Create or import a podcast title: Create or import a podcast
--- ---
You can create a new podcast or import an existing podcast into Castopod in the Podcasts section. If you are adding You can create a new podcast or import an existing podcast into Castopod in the
a second podcast to Castopod, see the [Home page documentation](../website#home-page) for how that will change your Podcasts section. If you are adding a second podcast to Castopod, see the
[Home page documentation](../website#home-page) for how that will change your
home page. home page.
From the left hand navigation sidebar, press the `+` sign to the right of Podcasts to create your first podcast. From the left hand navigation sidebar, press the `+` sign to the right of
Podcasts to create your first podcast.
## Podcast Identity ## Podcast Identity
### Podcast Cover ### Podcast Cover
To upload your podcast cover art, press the `Choose File` button and choose your cover art from your computer. The To upload your podcast cover art, press the `Choose File` button and choose your
cover art needs to be in JPG or PNG format and a minimum of 1400px wide and tall with a maximum of 3000px wide and cover art from your computer. The cover art needs to be in JPG or PNG format and
tall. a minimum of 1400px wide and tall with a maximum of 3000px wide and tall.
### Title ### Title
@ -22,13 +24,15 @@ Enter the name of your podcast in the **Title** field.
### Description ### Description
Describe what your podcast is about. You can use Markdown to style the text and you can resize the text box by Describe what your podcast is about. You can use Markdown to style the text and
pressing and holding the bottom right hand corner of the text box. you can resize the text box by pressing and holding the bottom right hand corner
of the text box.
### Type ### Type
Choose how your listeners should listen to your podcast. **Episodic** lets listeners know they can consume your podcast Choose how your listeners should listen to your podcast. **Episodic** lets
in any order, such as an interview podcast. Choose **Serial** if your episodes are meant to be listened to in listeners know they can consume your podcast in any order, such as an interview
podcast. Choose **Serial** if your episodes are meant to be listened to in
sequential order. sequential order.
### Medium ### Medium
@ -36,8 +40,10 @@ sequential order.
Choose the type of audio for your podcast: Choose the type of audio for your podcast:
- **Podcast**: a standard podcast. - **Podcast**: a standard podcast.
- **Music**: A feed of music organized into an "album" with each item a song within the album. - **Music**: A feed of music organized into an "album" with each item a song
- **Audiobook**: A specific type of audio with one item per feed, or where items represent chapters within a book. within the album.
- **Audiobook**: A specific type of audio with one item per feed, or where items
represent chapters within a book.
## Classification ## Classification
@ -47,7 +53,8 @@ From the dropdown menu, choose which language is spoken in your podcast.
### Category ### Category
Choose the category that represents your podcast, such as Arts, Comedy, Technology, etc. Choose the category that represents your podcast, such as Arts, Comedy,
Technology, etc.
### Other categories (optional) ### Other categories (optional)
@ -55,21 +62,25 @@ You can choose a second category in addition to the main category you set up.
### Parental advisory ### Parental advisory
Choose if your podcast has explicit content or swearing or choose Clean if your podcast is suitable for everyone. You Choose if your podcast has explicit content or swearing or choose Clean if your
can also choose to leave this category as undefined. When [creating a new episode](../podcast/episodes), podcast is suitable for everyone. You can also choose to leave this category as
you will also have the opportunity to choose clean, explicit, or undefined on a per episode basis. undefined. When [creating a new episode](../podcast/episodes), you will also
have the opportunity to choose clean, explicit, or undefined on a per episode
basis.
## Author ## Author
### Owner name and email ### Owner name and email
Enter the owner name and email in the provided fields. This is only visible in the RSS feed and is used by other Enter the owner name and email in the provided fields. This is only visible in
podcasting platforms to verify your ownership of your podcast. You can choose to remove the owner email the RSS feed and is used by other podcasting platforms to verify your ownership
from the public RSS feed by using the provided toggle. of your podcast. You can choose to remove the owner email from the public RSS
feed by using the provided toggle.
### Publisher ### Publisher
If your podcast is part of a podcast network or is produced by a company, enter the publisher here. If your podcast is part of a podcast network or is produced by a company, enter
the publisher here.
### Copyright ### Copyright
@ -77,69 +88,82 @@ You can optionally add the copyright holder in this field.
### Fediverse identity ### Fediverse identity
Enter the handle (or nickname) for your podcast. This will allow people on Mastodon and other Fediverse services Enter the handle (or nickname) for your podcast. This will allow people on
to follow your podcast. Your handle will be shown as @yourdomain.com@handle on the Fediverse. Mastodon and other Fediverse services to follow your podcast. Your handle will
be shown as @yourdomain.com@handle on the Fediverse.
To learn more about Fediverse integration, visit the [Fediverse documentation page](../instance/fediverse). To learn more about Fediverse integration, visit the
[Fediverse documentation page](../instance/fediverse).
### Podcast banner ### Podcast banner
Upload a banner image to be displayed at the top of your podcast's home page. The banner must have a 3:1 ration and Upload a banner image to be displayed at the top of your podcast's home page.
be at least 1500px wide. The banner must have a 3:1 ration and be at least 1500px wide.
### Premium ### Premium
Toggle this setting to set all episodes by default as premium. When creating an episode, it will default to premium, Toggle this setting to set all episodes by default as premium. When creating an
and you can still choose to make some episodes, trailers, or bonus content as free and public. episode, it will default to premium, and you can still choose to make some
episodes, trailers, or bonus content as free and public.
## Open Podcast Prefix Project (OP3) ## Open Podcast Prefix Project (OP3)
The [Open Podcast Prefix Project](https://op3.dev) is an open source and trusted third party analytics service. If The [Open Podcast Prefix Project](https://op3.dev) is an open source and trusted
you toggle this to enabled, you will be able to view analytics for your podcast over time including the number of third party analytics service. If you toggle this to enabled, you will be able
listens over time, episode comparison charts, and more. to view analytics for your podcast over time including the number of listens
over time, episode comparison charts, and more.
## Location ## Location
You can optionally add a real or fictitious location name in this field. When You can optionally add a real or fictitious location name in this field. When
[creating a new episode](../podcast/episodes) you also can add a location to an individual episode. [creating a new episode](../podcast/episodes) you also can add a location to an
individual episode.
## Advanced Parameters ## Advanced Parameters
You can optinally toggle the following settings: You can optinally toggle the following settings:
- **Prevent podcast from being copied**: this locks your podcast and does not allow other podcast platforms to import - **Prevent podcast from being copied**: this locks your podcast and does not
your podcast. If you decide in the future to migrate away from Castopod to a new platform, this toggle will need to be allow other podcast platforms to import your podcast. If you decide in the
unchecked. future to migrate away from Castopod to a new platform, this toggle will need
- **Podcast should be hidden from public catalogues**: If toggled, a best effort is made to hide the entire podcast from to be unchecked.
appearing in Apple Podcasts, YouTube Music, and any other third party podcast apps. (Not guaranteed) - **Podcast should be hidden from public catalogues**: If toggled, a best effort
- **Podcast will not be having new episodes**: If your podcast comes to an end, you can toggle this to let listeners is made to hide the entire podcast from appearing in Apple Podcasts, YouTube
know there will not be new episodes. Music, and any other third party podcast apps. (Not guaranteed)
- **Podcast will not be having new episodes**: If your podcast comes to an end,
you can toggle this to let listeners know there will not be new episodes.
## Import an existing podcast ## Import an existing podcast
When importing a podcast, make sure you own the rights for this podcast before importing it. When importing a podcast, make sure you own the rights for this podcast before
Copying and broadcasting a podcast without the proper rights is piracy and is liable to prosecution. importing it. Copying and broadcasting a podcast without the proper rights is
piracy and is liable to prosecution.
### Import the podcast ### Import the podcast
To import a podcast, enter the podcast's **Feed URL**. The feed must be in XML or RSS format. You may want to validate To import a podcast, enter the podcast's **Feed URL**. The feed must be in XML
the feed to make sure there are no errors in the RSS or XML feed prior to importing as errors may cause the import or RSS format. You may want to validate the feed to make sure there are no
to fail. One popular feed validator is [Cast Feed Validator](https://www.castfeedvalidator.com) from errors in the RSS or XML feed prior to importing as errors may cause the import
Blubrry Podcasting. to fail. One popular feed validator is
[Cast Feed Validator](https://www.castfeedvalidator.com) from Blubrry
Podcasting.
### Podcast information ### Podcast information
Enter the handle for your podcast. This will be part of the URL for others to interact with your podcast on the Enter the handle for your podcast. This will be part of the URL for others to
Fediverse. It will be yourdomain.com@nameofyourpodcast. interact with your podcast on the Fediverse. It will be
yourdomain.com@nameofyourpodcast.
Choose the language your podcast is recorded in from the drop down box. Choose the language your podcast is recorded in from the drop down box.
Lastly, choose the Category of your podcast, such as Sports, Technology, Arts, etc. Lastly, choose the Category of your podcast, such as Sports, Technology, Arts,
etc.
When complete, click Add import to queue. You will then be redirected to a Podcast imports page to view the status When complete, click Add import to queue. You will then be redirected to a
of the import. You can refresh the page to see the status of the import including the import duration and how many Podcast imports page to view the status of the import. You can refresh the page
to see the status of the import including the import duration and how many
episodes were imported when complete. episodes were imported when complete.
!!! note !!! note If your import times out, check your `max_execution_time` in your
If your import times out, check your `max_execution_time` in your `PHP.ini` file. You may need to increase it `PHP.ini` file. You may need to increase it from 30 seconds (the default) to add
from 30 seconds (the default) to add more time, such as 300 seconds (5 minutes) for larger podcasts. more time, such as 300 seconds (5 minutes) for larger podcasts.

22
docs/src/content/docs/en/user-guide/instance/settings.mdx
View File

@ -2,7 +2,8 @@
title: Settings title: Settings
--- ---
To change or update the settings for your instance, choose `Settings` from the left hand navigation. To change or update the settings for your instance, choose `Settings` from the
left hand navigation.
## General settings ## General settings
@ -18,21 +19,26 @@ Update description of your instance in the `Site description` text box.
#### Site icon #### Site icon
You can upload a site icon, also known as a favicon, by pressing `Choose file`. Site icons are what you see You can upload a site icon, also known as a favicon, by pressing `Choose file`.
on your browser tabs, bookmarks, and shortcuts on mobile devices. The image must be at least 500px tall and wide. Site icons are what you see on your browser tabs, bookmarks, and shortcuts on
mobile devices. The image must be at least 500px tall and wide.
### Images ### Images
If you come across broken or missing images on your site, press `Regenerate images`. This process may take time. If you come across broken or missing images on your site, press
`Regenerate images`. This process may take time.
### Housekeeping ### Housekeeping
You can run various tasks for your instance: You can run various tasks for your instance:
- **Reset counts**: This will reset and recalculate counts for followers, posts, and comments. - **Reset counts**: This will reset and recalculate counts for followers, posts,
- **Rename episode files**: This option renames all episodes files to a random name. If one of your private and comments.
episodes leaks, toggle this setting to effectively hide the episode. - **Rename episode files**: This option renames all episodes files to a random
- **Clear all cache**: This option will flush the Redis cache or writable / cache files. name. If one of your private episodes leaks, toggle this setting to
effectively hide the episode.
- **Clear all cache**: This option will flush the Redis cache or writable /
cache files.
## Theme ## Theme

20
docs/src/content/docs/en/user-guide/instance/users.mdx
View File

@ -2,15 +2,19 @@
title: Users title: Users
--- ---
Roles and permissions in Castopod are defined in two ways, **Instance** users and Roles and permissions in Castopod are defined in two ways, **Instance** users
[**Podcast**. contributors](../podcast/contributors). For a detailed list of permissions, view and [**Podcast**. contributors](../podcast/contributors). For a detailed list of
he [Auth](../../getting-started/auth) page. permissions, view he [Auth](../../getting-started/auth) page.
## Adding a User to the instance ## Adding a User to the instance
You can add a user to your instance by choosing `Users` -> `New User` from the left hand navigation menu. There You can add a user to your instance by choosing `Users` -> `New User` from the
are three roles you can assign to an instance user: left hand navigation menu. There are three roles you can assign to an instance
user:
- **Super Admin**: This user has complete control over Castopod including adding or removing podcasts or users. - **Super Admin**: This user has complete control over Castopod including adding
- **Manager**: This user can manage Castopod's content, such as adding or importing a new podcast and managing people. or removing podcasts or users.
- **Podcaster**: This is for general users of Castopod who can access the admin interface. - **Manager**: This user can manage Castopod's content, such as adding or
importing a new podcast and managing people.
- **Podcaster**: This is for general users of Castopod who can access the admin
interface.

31
docs/src/content/docs/en/user-guide/podcast/analytics.mdx
View File

@ -2,22 +2,24 @@
title: Analytics title: Analytics
--- ---
Castopod comes with a number of different analytics and statistics about your podcast(s). From the left hand Castopod comes with a number of different analytics and statistics about your
navigation, choose `Analytics` to view the various options. podcast(s). From the left hand navigation, choose `Analytics` to view the
various options.
## Audience overview ## Audience overview
This page provides an overview of your episode's daily downloads, monthly downloads, and daily bandwidth used. This page provides an overview of your episode's daily downloads, monthly
downloads, and daily bandwidth used.
## Unique listeners ## Unique listeners
View graphs of the number of daily and monthly users of your podcast. Use the zoom function at the top of each View graphs of the number of daily and monthly users of your podcast. Use the
graph to zoom in or out. zoom function at the top of each graph to zoom in or out.
## Listening time ## Listening time
View graphs of your listener's daily and monthly cumulative listening time. Use the zoom function at the top of each View graphs of your listener's daily and monthly cumulative listening time. Use
graph to zoom in or out. the zoom function at the top of each graph to zoom in or out.
## Players ## Players
@ -28,8 +30,9 @@ This page provides four pie charts to view statistics for the last week:
- Episode downloads by device - Episode downloads by device
- Episode downloads by operating system - Episode downloads by operating system
You can hover over each graph and press the three dots to download statistics for the graph you are hovering over. You can hover over each graph and press the three dots to download statistics
You can interact with the graphs to download or print: for the graph you are hovering over. You can interact with the graphs to
download or print:
- Image (PNG, JPG, SVG, or PDF) - Image (PNG, JPG, SVG, or PDF)
- Data (JSON, CSV, XLSX, HTML, or PDF) - Data (JSON, CSV, XLSX, HTML, or PDF)
@ -37,13 +40,15 @@ You can interact with the graphs to download or print:
## Locations ## Locations
You can view where your listeners are located by choosing _Locations_. Two pie charts are available showing You can view where your listeners are located by choosing _Locations_. Two pie
episode downloads by country for the past week and past year. At the bottom of the page, you can view a world map charts are available showing episode downloads by country for the past week and
showing your listener's locations. past year. At the bottom of the page, you can view a world map showing your
listener's locations.
## Time periods ## Time periods
Two bar graphs displaying the week day and time of day your listeners listen to your podcsat. Two bar graphs displaying the week day and time of day your listeners listen to
your podcsat.
## Web pages visits ## Web pages visits

40
docs/src/content/docs/en/user-guide/podcast/broadcast.mdx
View File

@ -4,31 +4,35 @@ title: Broadcast your podcast
## Add your podcast to podcast directories ## Add your podcast to podcast directories
Listeners can add your RSS feed to their podcast app of choice to subscribe to your podcast. Most listeners will Listeners can add your RSS feed to their podcast app of choice to subscribe to
find your podcast in a podcast directory, such as Apple Podcasts, YouTube Music, Spotify, or the Podcast Index. your podcast. Most listeners will find your podcast in a podcast directory, such
These four are the most popular podcast directories and a number of other directories pull their data from Apple as Apple Podcasts, YouTube Music, Spotify, or the Podcast Index. These four are
Podcasts. the most popular podcast directories and a number of other directories pull
their data from Apple Podcasts.
Visit [Podnews](https://podnews.net/article/all-the-podcast-directories) to learn how to add your podcast to Visit [Podnews](https://podnews.net/article/all-the-podcast-directories) to
most of the podcast directories. learn how to add your podcast to most of the podcast directories.
Once your podcast is listed in the podcast directories, you can link to them on your home page by choosing Once your podcast is listed in the podcast directories, you can link to them on
`Broadcast` from the left hand navigation. your home page by choosing `Broadcast` from the left hand navigation.
### Podcasting Apps ### Podcasting Apps
Castopod provides the ability to link to a majority of podcast directories where users can find your podcast. Castopod provides the ability to link to a majority of podcast directories where
For each directory listed fill out the link to your podcast in a specific directory and the ID. If you want users can find your podcast. For each directory listed fill out the link to your
an icon displayed on your home page, toggle `Display in podcast homepage?`. podcast in a specific directory and the ID. If you want an icon displayed on
your home page, toggle `Display in podcast homepage?`.
After pressing `Save` in the upper right hand corner, visit your home page to see the icons with hyperlinks After pressing `Save` in the upper right hand corner, visit your home page to
on the right hand side of your home page under _Listen on_. see the icons with hyperlinks on the right hand side of your home page under
_Listen on_.
### Social Networks ### Social Networks
If your podcast has a presence on social networks, Castopod provides the ability to link to your social network If your podcast has a presence on social networks, Castopod provides the ability
profiles. Add the link to your profile page in the text field and toggle if you want it displayed on your to link to your social network profiles. Add the link to your profile page in
home page. the text field and toggle if you want it displayed on your home page.
After pressing `Save` in the upper right hand corner, visit your home page to see the icons with hyperlinks After pressing `Save` in the upper right hand corner, visit your home page to
on the right hand side of your home page under _Find your podcast on_. see the icons with hyperlinks on the right hand side of your home page under
_Find your podcast on_.

16
docs/src/content/docs/en/user-guide/podcast/contributors.mdx
View File

@ -2,8 +2,9 @@
title: Contributors title: Contributors
--- ---
From the podcast dashboard, click **Contributors** to add or edit users to have access to the podcast and its settings. From the podcast dashboard, click **Contributors** to add or edit users to have
For a detailed list of permissions, view the [Auth](../../getting-started/auth) page. access to the podcast and its settings. For a detailed list of permissions, view
the [Auth](../../getting-started/auth) page.
## Roles ## Roles
@ -15,14 +16,15 @@ The admin user has complete control over the individual podcast.
### Editor ### Editor
The editor has access to management functions including podcast import, managing persons, creating or deleting The editor has access to management functions including podcast import, managing
episodes, and managing clips. persons, creating or deleting episodes, and managing clips.
### Author ### Author
The autorh can manage content of the podcast, but cannot publish an episode. They can manage The autorh can manage content of the podcast, but cannot publish an episode.
[contributors](contributors), create clips, and create episodes. They can manage [contributors](contributors), create clips, and create episodes.
### Guest ### Guest
The guest can view the podcast dashboard and view episodes. They cannot edit or add any content. The guest can view the podcast dashboard and view episodes. They cannot edit or
add any content.

52
docs/src/content/docs/en/user-guide/podcast/dashboard.mdx
View File

@ -2,49 +2,59 @@
title: Podcast Dashboard title: Podcast Dashboard
--- ---
When you choose your podcast from the Admin dashboard you will be redirected to the Podcast dashboard page. When you choose your podcast from the Admin dashboard you will be redirected to
the Podcast dashboard page.
The Podcast dashboard shows you up to five of the latest episodes, both those published and scheduled. You can click The Podcast dashboard shows you up to five of the latest episodes, both those
on any of these episodes to view them or click `See all episodes` to see a list of every episode. published and scheduled. You can click on any of these episodes to view them or
click `See all episodes` to see a list of every episode.
## Edit your podcast ## Edit your podcast
To edit your podcast, press `Edit podcast` in the upper right hand corner or `Edit podcast` in the left hand side To edit your podcast, press `Edit podcast` in the upper right hand corner or
navigation. `Edit podcast` in the left hand side navigation.
You can edit any of the [fields you filled out when creating your podcast](../instance/podcast). You can edit any of the
[fields you filled out when creating your podcast](../instance/podcast).
When finished press the `Save podcast` button in the upper right hand corner. When finished press the `Save podcast` button in the upper right hand corner.
You can also choose to delete your podcast by pressing `Delete podcast` at the bottom of the Edit podcast page. You can also choose to delete your podcast by pressing `Delete podcast` at the
bottom of the Edit podcast page.
## Manage persons ## Manage persons
If you have added people to Persons in the Admin dashboard, you can assign them a role here. People assigned roles If you have added people to Persons in the Admin dashboard, you can assign them
will show up on the [Credits page](../website/credits) linked from your home page to give them a role here. People assigned roles will show up on the
[Credits page](../website/credits) linked from your home page to give them
credit for contributing to the podcast. credit for contributing to the podcast.
Roles include Administration, Audio production, cast, guests, hosts, writing, and more. Roles include Administration, Audio production, cast, guests, hosts, writing,
and more.
From the **Persons** drop down, choose the person you want to add. Then choose a role from the \*_Roles_ drop down and From the **Persons** drop down, choose the person you want to add. Then choose a
press `Add person(s)`. role from the \*_Roles_ drop down and press `Add person(s)`.
A list of all people assigned roles will be displayed. You can remove them by pressing the `Remove` button. A list of all people assigned roles will be displayed. You can remove them by
pressing the `Remove` button.
Adding persons to your podcast populates the Credits page linked from your Adding persons to your podcast populates the Credits page linked from your
[home page](../website). [home page](../website).
## Podcast imports ## Podcast imports
Podcast imports show you the status of a feed that you imported into Castopod, including the feed name, Podcast imports show you the status of a feed that you imported into Castopod,
how long the import took, and how many episodes were imported. Under **Actions** you can try re-import the feed including the feed name, how long the import took, and how many episodes were
if the original import failed or delete the status message for the imported feed. imported. Under **Actions** you can try re-import the feed if the original
import failed or delete the status message for the imported feed.
If the feed you imported has been updated after your import, press `Synchronize Feeds` in the upper right hand If the feed you imported has been updated after your import, press
corner to import the missing episodes. `Synchronize Feeds` in the upper right hand corner to import the missing
episodes.
## Sync feeds ## Sync feeds
You can also synchronize missing episode from an imported feed by choosing `Sync Feeds` from the Podcast dashboard You can also synchronize missing episode from an imported feed by choosing
menu. The **Feed URL** should auto-populate if you have previously imported a feed. Press `Add to queue` to import `Sync Feeds` from the Podcast dashboard menu. The **Feed URL** should
any missing episodes from the feed. auto-populate if you have previously imported a feed. Press `Add to queue` to
import any missing episodes from the feed.

146
docs/src/content/docs/en/user-guide/podcast/episodes.mdx
View File

@ -2,130 +2,150 @@
title: Episodes title: Episodes
--- ---
From the left hand navigation, click **Episodes** and the menu will expand to **All Episodes** and **New Episode**. From the left hand navigation, click **Episodes** and the menu will expand to
**All Episodes** and **New Episode**.
## All Episodes ## All Episodes
To view a list of all episodes, click `All Episodes`. Each episode will be displayed in a list with its name and To view a list of all episodes, click `All Episodes`. Each episode will be
notes, Visibility such as published or scheduled, and how many downloads and comments each episode has. displayed in a list with its name and notes, Visibility such as published or
scheduled, and how many downloads and comments each episode has.
### Actions and the Episode Dashboard ### Actions and the Episode Dashboard
Click the three dots under **Actions** to view a menu of options for an episode or click on an individual episode to Click the three dots under **Actions** to view a menu of options for an episode
view the available actions: or click on an individual episode to view the available actions:
- **Go to page**: This will redirect you to the public page of the episode and display the show notes. - **Go to page**: This will redirect you to the public page of the episode and
- **Edit**: This allows you to change the fields you filled when creating the episode (see below). display the show notes.
- **Edit**: This allows you to change the fields you filled when creating the
episode (see below).
### Embeddable player ### Embeddable player
Choose a theme color and press the copy button to the right of the text box to copy the Choose a theme color and press the copy button to the right of the text box to
code to your clipboard. Insert the code into a web page to display the episode. copy the code to your clipboard. Insert the code into a web page to display the
episode.
### Persons ### Persons
If you have added people in the Admin interface, you can choose a person and assign them a role, such If you have added people in the Admin interface, you can choose a person and
as guest, for a given episode. assign them a role, such as guest, for a given episode.
### Video clips and Soundbites ### Video clips and Soundbites
The process to create a video clip and soundbite is the same. It may take a minute for the file to load and you The process to create a video clip and soundbite is the same. It may take a
will see the waveform. minute for the file to load and you will see the waveform.
A video clip will create an MP4 video of the audio with text from the transcript matched to the audio. A soundbite A video clip will create an MP4 video of the audio with text from the transcript
will create an audio clip. matched to the audio. A soundbite will create an audio clip.
Enter the name of the clip you want to create. Then drag the slider to where you want to start and end your Enter the name of the clip you want to create. Then drag the slider to where you
video clip or soundbite. You can press the `Play` button to preview your clip. want to start and end your video clip or soundbite. You can press the `Play`
button to preview your clip.
For video clips, choose a format, including Landscape, Portrait or Squared and a background theme color. For video clips, choose a format, including Landscape, Portrait or Squared and a
background theme color.
Then press the `Create` button, you will be redirected to a status page displaying the status of creating the clip. Then press the `Create` button, you will be redirected to a status page
Refresh the page to see if it's `Running` or completed. You may need to be patient depending on the length of the clip. displaying the status of creating the clip. Refresh the page to see if it's
`Running` or completed. You may need to be patient depending on the length of
the clip.
:::note :::note To create video clips and soundbites, your server must have `FFMPEG`
To create video clips and soundbites, your server must have `FFMPEG` installed and a transcript. installed and a transcript. :::
:::
## Create episode ## Create episode
To add an episode, press the `Add an episode button` in the upper right hand corner of the Episode dashboard or click To add an episode, press the `Add an episode button` in the upper right hand
`New episode` in the left hand navigation under `Episodes`. corner of the Episode dashboard or click `New episode` in the left hand
navigation under `Episodes`.
### Episode Info ### Episode Info
#### Audio file #### Audio file
Press the `Choose File` button to select the audio file to upload to Castopod. The audio file must be an mp3 or m4a Press the `Choose File` button to select the audio file to upload to Castopod.
file and cannot be larger than 512 megabytes. The audio file must be an mp3 or m4a file and cannot be larger than 512
megabytes.
### Episode cover ### Episode cover
You can optionally add a different podcast cover / artwork. Press `Choose File` and select an image from your computer You can optionally add a different podcast cover / artwork. Press `Choose File`
that must be at least 1400px wide and tall and no larger than 3000px wide and tall. If you do not choose an and select an image from your computer that must be at least 1400px wide and
episode cover, your default podcast artwork will be used. tall and no larger than 3000px wide and tall. If you do not choose an episode
cover, your default podcast artwork will be used.
#### Title #### Title
Enter the name for your new episode. Do not add the season or episode number in the **Title** field. Choose a clear Enter the name for your new episode. Do not add the season or episode number in
and concise episode name to help your listeners. the **Title** field. Choose a clear and concise episode name to help your
listeners.
#### Permalink #### Permalink
The permalink is the link to the public episode page. This will be automatically filled out based on the title The permalink is the link to the public episode page. This will be automatically
you entered above. If you wish to have a different permalink, press the edit button to the right of the filled out based on the title you entered above. If you wish to have a different
displayed permalink. permalink, press the edit button to the right of the displayed permalink.
#### Season and Episode #### Season and Episode
You can optionally add a season and / or episode number to your episode. If you are adding a new episode and a You can optionally add a season and / or episode number to your episode. If you
previous episode had a season and /or episode number, the field(s) will be auto filled for you. You can leave it or are adding a new episode and a previous episode had a season and /or episode
update with a different season and / or episode number. number, the field(s) will be auto filled for you. You can leave it or update
with a different season and / or episode number.
### Show Notes ### Show Notes
Describe your episode in detail. You can use up to 4000 characters, and you can use Markdown to style your show Describe your episode in detail. You can use up to 4000 characters, and you can
notes. You can expand the text box by pressing and holding the bottom right corner of the text box. use Markdown to style your show notes. You can expand the text box by pressing
and holding the bottom right corner of the text box.
When your show notes are complete, press `Preview` to view how your show notes will be displayed. When your show notes are complete, press `Preview` to view how your show notes
will be displayed.
### Additional Files ### Additional Files
#### Transcripts #### Transcripts
You can add a transcript to your episode by choosing a file in SRT or VTT format to upload. Transcripts will be You can add a transcript to your episode by choosing a file in SRT or VTT format
shown in a tab on the episode page and some podcast apps such as Apple Podcasts can display the transcript. to upload. Transcripts will be shown in a tab on the episode page and some
Transcripts help users who may have a hearing disability and can also help with search engine optimization. podcast apps such as Apple Podcasts can display the transcript.
Transcripts help users who may have a hearing disability and can also help with
search engine optimization.
#### Chapters #### Chapters
You can optionally upload a chapters file in JSON format. To learn more about chapters and for an example of the You can optionally upload a chapters file in JSON format. To learn more about
correct format, visit the [Podcast Namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md). chapters and for an example of the correct format, visit the
[Podcast Namespace](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md).
:::note :::note Not all podcast players natively support chapters in JSON format. More
Not all podcast players natively support chapters in JSON format. More modern players, such as Fountain and modern players, such as Fountain and Apple Podcasts, do support chapters in JSON
Apple Podcasts, do support chapters in JSON format. Chapters do not allow you to click to select the chapter format. Chapters do not allow you to click to select the chapter in Castopod's
in Castopod's embeddable player at this time. embeddable player at this time. :::
:::
### Publish your episode ### Publish your episode
When complete, press the `Create episode` button at the bottom of the page. You will be automatically directed to When complete, press the `Create episode` button at the bottom of the page. You
the next step to publish your episode. Your episode is in draft mode and is not yet published. You can preview will be automatically directed to the next step to publish your episode. Your
how your episode will look when published or publish your episode. To publish your episode, press the `Publish` button episode is in draft mode and is not yet published. You can preview how your
in the upper right hand corner. episode will look when published or publish your episode. To publish your
episode, press the `Publish` button in the upper right hand corner.
### Create your announcement post ### Create your announcement post
After pressing `Publish` you will be directed to the next page to draft your announcement post. Write your message After pressing `Publish` you will be directed to the next page to draft your
in the text box provided. This will be the message broadcast to the Fediverse and published on your podcast's home announcement post. Write your message in the text box provided. This will be the
page. message broadcast to the Fediverse and published on your podcast's home page.
### Publication date ### Publication date
Choose `Now` or `Schedule` to publish your episode. If you choose `Now`, your episode will be live. Or you can Choose `Now` or `Schedule` to publish your episode. If you choose `Now`, your
schedule the day and time to publish your episode by choosing the `Schedule` radio button and choosing the day and episode will be live. Or you can schedule the day and time to publish your
time. Press `Publish` to finish. episode by choosing the `Schedule` radio button and choosing the day and time.
Press `Publish` to finish.
Your RSS feed will be automatically updated with your episode information and listeners who subscribe will be Your RSS feed will be automatically updated with your episode information and
notified of a new episode. Congratulations on publishing your first episode! listeners who subscribe will be notified of a new episode. Congratulations on
publishing your first episode!

9
docs/src/content/docs/en/user-guide/podcast/index.mdx
View File

@ -4,11 +4,12 @@ title: Manage Podcasts
import { LinkCard, CardGrid } from "@astrojs/starlight/components"; import { LinkCard, CardGrid } from "@astrojs/starlight/components";
From the Castopod admin interface, click **Podcasts** and then **All Podcasts** and you will be redirected to the From the Castopod admin interface, click **Podcasts** and then **All Podcasts**
podcast dashboard. This page displays the latest episodes, including any scheduled episodes. and you will be redirected to the podcast dashboard. This page displays the
latest episodes, including any scheduled episodes.
From the podcast dashboard, you can add episodes, view analytics, add links to your homepage, and more. Learn more From the podcast dashboard, you can add episodes, view analytics, add links to
by clicking the links below. your homepage, and more. Learn more by clicking the links below.
<CardGrid> <CardGrid>
<LinkCard title="Podcast dashboard" href="dashboard" /> <LinkCard title="Podcast dashboard" href="dashboard" />

76
docs/src/content/docs/en/user-guide/website/index.mdx
View File

@ -2,64 +2,75 @@
title: Podcast Home Page title: Podcast Home Page
--- ---
The podcast home page is your landing page for your listeners to view episode announcements, messages, episodes, The podcast home page is your landing page for your listeners to view episode
and links to where to find your podcast. If you have only one podcast, your users will be automatically redirected announcements, messages, episodes, and links to where to find your podcast. If
from your top level domain, such as `www.yourpodcast.com`, to the podcast page at you have only one podcast, your users will be automatically redirected from your
top level domain, such as `www.yourpodcast.com`, to the podcast page at
`www.yourpodcast.com/yourpodcasthandle`. `www.yourpodcast.com/yourpodcasthandle`.
If you are hosting multiple podcasts, your top level page will display the artwork for each podcast. Clicking on If you are hosting multiple podcasts, your top level page will display the
the podcast artwork will take you to your podcast page at `www.yourpodcast.com/yourpodcasthandle`. artwork for each podcast. Clicking on the podcast artwork will take you to your
podcast page at `www.yourpodcast.com/yourpodcasthandle`.
## Home Page ## Home Page
If you are logged in to your podcast, you will see a strip across the top of the page with a link to the admin If you are logged in to your podcast, you will see a strip across the top of the
interface of your podcast, a bell that will show if you have any new notifications, and the user who is logged in. page with a link to the admin interface of your podcast, a bell that will show
You can click on the user for quick access to your account, changing your password, or to log out. if you have any new notifications, and the user who is logged in. You can click
on the user for quick access to your account, changing your password, or to log
out.
:::note :::note If you have multiple podcasts, you can click the user dropdown to switch
If you have multiple podcasts, you can click the user dropdown to switch to choose which podcast to interact with. to choose which podcast to interact with. If your account has access to two or
If your account has access to two or more podcasts, pay attention to which podcast is broadcasting messages! more podcasts, pay attention to which podcast is broadcasting messages! :::
:::
Listeners can click the `Follow` button to follow any messages, including episode announcements, from a Fediverse Listeners can click the `Follow` button to follow any messages, including
app, such as Mastodon. After clicking `Follow` a pop-up box will be displayed where the user enterse their Fediverse episode announcements, from a Fediverse app, such as Mastodon. After clicking
`Follow` a pop-up box will be displayed where the user enterse their Fediverse
handle and then clicks `Proceed to follow`. handle and then clicks `Proceed to follow`.
### Podcast RSS feed ### Podcast RSS feed
On the right hand side is a link to your RSS Podcast feed. Users can copy that and subscribe directly in their On the right hand side is a link to your RSS Podcast feed. Users can copy that
podcast app. and subscribe directly in their podcast app.
### Social Networks ### Social Networks
Below the RSS feed is are icons that link to all of the social networks you toggled on in the Below the RSS feed is are icons that link to all of the social networks you
[Broadcast](../podcast/broadcast#podcasting-apps) section of the podcast's admin section. toggled on in the [Broadcast](../podcast/broadcast#podcasting-apps) section of
the podcast's admin section.
### Podcast Directories ### Podcast Directories
Below the social networking links is **Listen On** which displays icons linked to the podcast directories you Below the social networking links is **Listen On** which displays icons linked
toggled on in the [Broadcast](../podcast/broadcast#social-networks) section of the podcast's to the podcast directories you toggled on in the
admin section. [Broadcast](../podcast/broadcast#social-networks) section of the podcast's admin
section.
## Activity ## Activity
The **Activity** tab is located directly under your podcast artwork is the default home page for your podcast. Website The **Activity** tab is located directly under your podcast artwork is the
visitors are presented with a list of messages in chronological order. If you are logged in as a podcast default home page for your podcast. Website visitors are presented with a list
administrator, you will see a text box where you can write a message to be broadcasted to your followers. If you of messages in chronological order. If you are logged in as a podcast
include the episode URL, a preview of that episode will be included in your message. administrator, you will see a text box where you can write a message to be
broadcasted to your followers. If you include the episode URL, a preview of that
episode will be included in your message.
Below each message there are four icons: Below each message there are four icons:
- **Comments**: This will show you the number of comments on a given message. Clicking this will show you all replies to - **Comments**: This will show you the number of comments on a given message.
your message. You can click the three dots to block a user or a domain in case of spam. Clicking this will show you all replies to your message. You can click the
- **Shares**: This shows the number of times your message was shared by other users. three dots to block a user or a domain in case of spam.
- **Shares**: This shows the number of times your message was shared by other
users.
- **Favorites**: This shows how many people liked your message. - **Favorites**: This shows how many people liked your message.
## Episodes ## Episodes
The **Episodes** tab shows a list of all episode announcements you have shared. If you are using season numbers, it The **Episodes** tab shows a list of all episode announcements you have shared.
will default to the current season. Users can click the **Season** link above all of the messages for a dropdown menu If you are using season numbers, it will default to the current season. Users
to view past episodes by season. can click the **Season** link above all of the messages for a dropdown menu to
view past episodes by season.
## About ## About
@ -67,7 +78,8 @@ The About tab shares general information about your podcast, including:
- Podcast description - Podcast description
- Podcast category - Podcast category
- The [people](../podcast/dashboard#manage-persons) who contribute to the podcast - The [people](../podcast/dashboard#manage-persons) who contribute to the
podcast
- Statistics - Statistics
- Number of seasons - Number of seasons
- Number of episodes - Number of episodes

687
modules/Api/Rest/V1/podcast.json
View File

@ -1,687 +0,0 @@
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Castopod podcasts"
},
"paths": {
"/api/rest/v1/podcasts": {
"get": {
"summary": "List all podcasts",
"responses": {
"200": {
"description": "Object of podcasts",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Podcasts"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/podcasts/{id}": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the podcast to retrieve",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
}
}
],
"get": {
"summary": "Info for a specific podcast",
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Podcast"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/episodes": {
"get": {
"summary": "List all episodes",
"responses": {
"200": {
"description": "Object of episodes",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Episodes"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Create a new episode",
"requestBody": {
"description": "Episode object that needs to be added",
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/EpisodeCreateRequest"
}
}
}
},
"responses": {
"201": {
"description": "Episode created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Episode"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/episodes/{id}": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the episode to retrieve",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
}
}
],
"get": {
"summary": "Info for a specific episode",
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Episode"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/rest/v1/episodes/{id}/publish": {
"post": {
"summary": "Publish an episode",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the episode to publish",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
}
}
],
"requestBody": {
"description": "Publish parameters",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EpisodePublishRequest"
}
}
}
},
"responses": {
"200": {
"description": "Episode published successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Episode"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Podcast": {
"type": "object",
"required": [
"id",
"guid",
"actor_id",
"handle",
"title",
"description_markdown",
"description_html",
"cover_id",
"language_code",
"category_id",
"owner_name",
"owner_email",
"type",
"is_blocked",
"is_completed",
"is_locked",
"is_published_on_hubs",
"created_by",
"updated_by",
"created_at",
"updated_at",
"feed_url"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"guid": {
"type": "string",
"maxLength": 36
},
"actor_id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"handle": {
"type": "string",
"maxLength": 32
},
"title": {
"type": "string",
"maxLength": 128
},
"description_markdown": {
"type": "string"
},
"description_html": {
"type": "string"
},
"cover_id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"banner_id": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"language_code": {
"type": "string",
"maxLength": 2
},
"category_id": {
"type": "integer",
"format": "int64",
"minimum": 1
},
"parental_advisory": {
"type": "string",
"enum": ["clean", "explicit"]
},
"owner_name": {
"type": "string",
"maxLength": 128
},
"owner_email": {
"type": "string",
"maxLength": 255
},
"publisher": {
"type": "string",
"maxLength": 128
},
"type": {
"type": "string",
"enum": ["episodic", "serial"]
},
"copyright": {
"type": "string",
"maxLength": 128
},
"episode_description_footer_markdown": {
"type": "string"
},
"episode_description_footer_html": {
"type": "string"
},
"is_blocked": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"is_completed": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"is_locked": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"imported_feed_url": {
"type": "string",
"maxLength": 512
},
"new_feed_url": {
"type": "string",
"maxLength": 512
},
"payment_pointer": {
"type": "string",
"maxLength": 128
},
"location_name": {
"type": "string",
"maxLength": 128
},
"location_geo": {
"type": "string",
"maxLength": 32
},
"location_osm": {
"type": "string",
"maxLength": 12
},
"custom_rss": {
"type": "string"
},
"is_published_on_hubs": {
"type": "integer",
"format": "int32",
"enum": [0, 1],
"minLength": 1
},
"partner_id": {
"type": "string",
"maxLength": 32
},
"partner_link_url": {
"type": "string",
"maxLength": 512
},
"partner_image_url": {
"type": "string",
"maxLength": 512
},
"created_by": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"updated_by": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maxLength": 10
},
"created_at": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date-time"
},
"timezone_type": {
"type": "integer",
"format": "int32"
},
"timezone": {
"type": "string"
}
}
},
"updated_at": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date-time"
},
"timezone_type": {
"type": "integer",
"format": "int32"
},
"timezone": {
"type": "string"
}
}
},
"feed_url": {
"type": "string"
}
}
},
"Podcasts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Podcast"
}
},
"Episode": {
"type": "object",
"required": [
"id",
"title",
"slug",
"podcast_id",
"created_by",
"updated_by",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"podcast_id": {
"type": "integer",
"format": "int64"
},
"description_markdown": {
"type": "string"
},
"description_html": {
"type": "string"
},
"audio_url": {
"type": "string",
"format": "uri"
},
"cover_url": {
"type": "string",
"format": "uri"
},
"duration": {
"type": "integer",
"format": "int32"
},
"published_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "integer",
"format": "int64"
},
"updated_by": {
"type": "integer",
"format": "int64"
}
}
},
"Episodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Episode"
}
},
"EpisodeCreateRequest": {
"type": "object",
"required": [
"user_id",
"updated_by",
"title",
"slug",
"podcast_id",
"audio_file"
],
"properties": {
"user_id": {
"type": "integer",
"format": "int64",
"description": "ID of the user creating the episode"
},
"updated_by": {
"type": "integer",
"format": "int64",
"description": "ID of the user updating the episode"
},
"title": {
"type": "string",
"description": "Title of the episode"
},
"slug": {
"type": "string",
"description": "URL-friendly slug of the episode"
},
"podcast_id": {
"type": "integer",
"format": "int64",
"description": "ID of the podcast the episode belongs to"
},
"audio_file": {
"type": "string",
"format": "binary",
"description": "Audio file for the episode"
},
"cover": {
"type": "string",
"format": "binary",
"description": "Cover image for the episode"
},
"description": {
"type": "string",
"description": "Description of the episode"
},
"location_name": {
"type": "string",
"description": "Location associated with the episode"
},
"parental_advisory": {
"type": "string",
"enum": ["clean", "explicit"],
"description": "Parental advisory rating"
},
"episode_number": {
"type": "integer",
"format": "int32",
"description": "Episode number (for serial podcasts)"
},
"season_number": {
"type": "integer",
"format": "int32",
"description": "Season number (for serial podcasts)"
},
"type": {
"type": "string",
"enum": ["full", "trailer", "bonus"],
"description": "Type of episode"
},
"block": {
"type": "string",
"enum": ["yes", "no"],
"description": "Block episode from being published"
},
"custom_rss": {
"type": "string",
"description": "Custom RSS content"
},
"premium": {
"type": "string",
"enum": ["yes", "no"],
"description": "Mark episode as premium content"
},
"transcript-choice": {
"type": "string",
"enum": ["upload-file", "remote-url"],
"description": "Transcript source choice"
},
"transcript_file": {
"type": "string",
"format": "binary",
"description": "Transcript file"
},
"transcript_remote_url": {
"type": "string",
"format": "uri",
"description": "Remote URL for transcript"
},
"chapters-choice": {
"type": "string",
"enum": ["upload-file", "remote-url"],
"description": "Chapters source choice"
},
"chapters_file": {
"type": "string",
"format": "binary",
"description": "Chapters file"
},
"chapters_remote_url": {
"type": "string",
"format": "uri",
"description": "Remote URL for chapters"
}
}
},
"EpisodePublishRequest": {
"type": "object",
"required": ["publication_method"],
"properties": {
"publication_method": {
"type": "string",
"enum": ["now", "schedule", "with_podcast"],
"description": "Method of publication"
},
"scheduled_publication_date": {
"type": "string",
"format": "date-time",
"description": "Scheduled date and time for publication"
},
"client_timezone": {
"type": "string",
"description": "Timezone of the client"
}
}
},
"Error": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"format": "int32"
},
"error": {
"type": "integer",
"format": "int32"
},
"messages": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
}
}
}
}
}
}
}

502
modules/Api/Rest/V1/schema.yaml Normal file
View File

@ -0,0 +1,502 @@
openapi: 3.1.0
info:
version: 1.0.0
title: Castopod API
license:
name: AGPL v3
url: https://code.castopod.org/adaures/castopod/-/blob/develop/LICENSE.md
paths:
/podcasts:
get:
summary: Get all podcasts
operationId: get-all-podcasts
responses:
"200":
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Podcast"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/podcasts/{podcastId}:
parameters:
- name: podcastId
in: path
description: The id of the podcast to retrieve
required: true
schema:
type: integer
format: int64
get:
summary: Get podcast by ID
description: Returns a single podcast
operationId: get-podcast-by-id
responses:
"200":
description: Successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/Podcast"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/episodes:
get:
summary: Get all episodes
operationId: get-all-episodes
responses:
"200":
description: Object of episodes
content:
application/json:
schema:
type: "array"
items:
$ref: "#/components/schemas/Episode"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
post:
summary: Add a new episode
operationId: add-episode
requestBody:
description: Episode object that needs to be added
required: true
content:
multipart/form-data:
schema:
$ref: "#/components/schemas/EpisodeCreateRequest"
responses:
"201":
description: Episode created successfully
content:
application/json:
schema:
$ref: "#/components/schemas/Episode"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/episodes/{episodeId}:
parameters:
- name: episodeId
in: path
description: The id of the episode to retrieve
required: true
schema:
type: integer
format: int64
get:
summary: Get episode by ID
description: Returns a single episode
operationId: get-episode-by-id
responses:
"200":
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Episode"
default:
description: Unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/episodes/{episodeId}/publish:
post:
summary: Publish an episode
operationId: publish-episode
parameters:
- name: episodeId
in: path
description: The id of the episode to publish
required: true
schema:
type: integer
format: int64
requestBody:
description: Publish parameters
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/EpisodePublishRequest"
responses:
"200":
description: Successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/Episode"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Podcast:
type: object
required:
- id
- guid
- actor_id
- handle
- title
- description_markdown
- description_html
- cover_id
- language_code
- category_id
- owner_name
- owner_email
- type
- is_blocked
- is_completed
- is_locked
- is_published_on_hubs
- created_by
- updated_by
- created_at
- updated_at
- feed_url
properties:
id:
type: integer
format: int64
guid:
type: string
maxLength: 36
actor_id:
type: integer
format: int64
handle:
type: string
maxLength: 32
title:
type: string
maxLength: 128
description_markdown:
type: string
description_html:
type: string
cover_id:
type: integer
format: int64
banner_id:
type: integer
format: int64
language_code:
type: string
maxLength: 2
category_id:
type: integer
format: int64
minimum: 1
parental_advisory:
type: string
enum:
- clean
- explicit
owner_name:
type: string
maxLength: 128
owner_email:
type: string
maxLength: 255
publisher:
type: string
maxLength: 128
type:
type: string
enum:
- episodic
- serial
copyright:
type: string
maxLength: 128
episode_description_footer_markdown:
type: string
episode_description_footer_html:
type: string
is_blocked:
type: integer
format: int32
enum:
- 0
- 1
is_completed:
type: integer
format: int32
enum:
- 0
- 1
is_locked:
type: integer
format: int32
enum:
- 0
- 1
imported_feed_url:
type: string
maxLength: 512
new_feed_url:
type: string
maxLength: 512
location_name:
type: string
maxLength: 128
location_geo:
type: string
maxLength: 32
location_osm:
type: string
maxLength: 12
custom_rss:
type: string
is_published_on_hubs:
type: integer
format: int32
enum:
- 0
- 1
partner_id:
type: string
maxLength: 32
partner_link_url:
type: string
maxLength: 512
partner_image_url:
type: string
maxLength: 512
created_by:
type: integer
format: int64
updated_by:
type: integer
format: int64
created_at:
type: object
properties:
date:
type: string
format: date-time
timezone_type:
type: integer
format: int32
timezone:
type: string
updated_at:
type: object
properties:
date:
type: string
format: date-time
timezone_type:
type: integer
format: int32
timezone:
type: string
feed_url:
type: string
Episode:
type: object
required:
- id
- title
- slug
- podcast_id
- created_by
- updated_by
- created_at
- updated_at
properties:
id:
type: integer
format: int64
title:
type: string
slug:
type: string
podcast_id:
type: integer
format: int64
description_markdown:
type: string
description_html:
type: string
audio_url:
type: string
format: uri
cover_url:
type: string
format: uri
duration:
type: integer
format: int32
published_at:
type: string
format: date-time
created_by:
type: integer
format: int64
updated_by:
type: integer
format: int64
EpisodeCreateRequest:
type: object
required:
- user_id
- updated_by
- title
- slug
- podcast_id
- audio_file
properties:
user_id:
type: integer
format: int64
description: ID of the user creating the episode
updated_by:
type: integer
format: int64
description: ID of the user updating the episode
title:
type: string
description: Title of the episode
slug:
type: string
description: URL-friendly slug of the episode
podcast_id:
type: integer
format: int64
description: ID of the podcast the episode belongs to
audio_file:
type: string
format: binary
description: Audio file for the episode
cover:
type: string
format: binary
description: Cover image for the episode
description:
type: string
description: Description of the episode
location_name:
type: string
description: Location associated with the episode
parental_advisory:
type: string
enum:
- clean
- explicit
description: Parental advisory rating
episode_number:
type: integer
format: int32
description: Episode number (for serial podcasts)
season_number:
type: integer
format: int32
description: Season number (for serial podcasts)
type:
type: string
enum:
- full
- trailer
- bonus
description: Type of episode
block:
type: string
enum:
- "yes"
- "no"
description: Block episode from being published
custom_rss:
type: string
description: Custom RSS content
premium:
type: string
enum:
- "yes"
- "no"
description: Mark episode as premium content
transcript-choice:
type: string
enum:
- upload-file
- remote-url
description: Transcript source choice
transcript_file:
type: string
format: binary
description: Transcript file
transcript_remote_url:
type: string
format: uri
description: Remote URL for transcript
chapters-choice:
type: string
enum:
- upload-file
- remote-url
description: Chapters source choice
chapters_file:
type: string
format: binary
description: Chapters file
chapters_remote_url:
type: string
format: uri
description: Remote URL for chapters
EpisodePublishRequest:
type: object
required:
- publication_method
properties:
publication_method:
type: string
enum:
- now
- schedule
- with_podcast
description: Method of publication
scheduled_publication_date:
type: string
format: date-time
description: Scheduled date and time for publication
client_timezone:
type: string
description: Timezone of the client
Error:
type: object
properties:
status:
type: integer
format: int32
error:
type: integer
format: int32
messages:
type: object
properties:
error:
type: string