Merge pull request #18 from owlot/feature/audio-directive

feat: embed audio players from local sound files via ::: audio directive

Author: mvanholsteijn

README.md

@@ -5,6 +5,7 @@ in your favorite editor and keeps all your blogs in git.
 ## features
 - converts markdown into plain html, with syntax hightlighting support
 - uploads and synchronizes any locally referenced images
+- embeds audio players from locally referenced sound files
 - generates an opengraph image including the title, subtitle and author in Binx.io or xebia.com style
 - sets the Rankmath focus keywords
 - sets the canonical url, if specified
@@ -122,6 +123,21 @@ To add an image to your blog, add the images in the ./images subdirectory and ad
 ![](./images/architecture.png)
 ```
 
+## adding audio
+To embed an audio player, add the sound file in a subdirectory (for example `./audio`)
+and add an `::: audio` directive on its own line, with a relative reference. For instance:
+
+```markdown
+## Listen to this section
+
+::: audio ./audio/section-one.mp3
+```
+
+The sound file is uploaded and synchronized just like an image, and rendered as a native
+Wordpress audio block (a player with controls) at that position. Drop one directive under
+each heading to give every section its own player. Remote URLs (`https://...`) are embedded
+as-is without uploading.
+
 ## uploading a blog
 To upload a blog, type:
 

src/wordpress_markdown_blog_loader/blog.py

@@ -29,9 +29,14 @@ def __init__(self):
         self.path: Path = None
         self.blog: frontmatter.Post = frontmatter.Post(content="")
         self.uploaded_images: dict[str, Media] = {}
+        self.uploaded_audio: dict[str, Medium] = {}
         self.markdown_image_pattern = re.compile(
             r'\!\[(?P<alt_text>[^]]*)\]\((?P<url>.*?)(?P<caption>\s*"[^"]*?")?\)'
         )
+        # An audio player directive on its own line: `::: audio path/to/clip.mp3`
+        self.audio_directive_pattern = re.compile(
+            r"^[ \t]*:::[ \t]+audio[ \t]+(?P<url>\S+)[ \t]*$", re.MULTILINE
+        )
 
     @staticmethod
     def load(path: str) -> "Blog":
@@ -306,7 +311,19 @@ def replace_references(match: re.Match):
                 return f"![{match.group('alt_text')}]({image.url}{caption})"
             return match.group(0)
 
+        def replace_audio_directive(match: re.Match):
+            url = match.group("url")
+            audio = self.uploaded_audio.get(url)
+            src = audio.url if audio else url
+            # raw block-level HTML; python-markdown passes it through untouched,
+            # and html_to_gutenberg turns it into a wp:audio block.
+            return (
+                f'<figure class="wp-block-audio">'
+                f'<audio controls src="{src}"></audio></figure>'
+            )
+
         content = self.markdown_image_pattern.sub(replace_references, self.content)
+        content = self.audio_directive_pattern.sub(replace_audio_directive, content)
         html = markdown(
             content, extensions=["fenced_code", "attr_list", "tables", "footnotes"],
         )
@@ -395,9 +412,41 @@ def upload_local_images(self, wp: Wordpress):
             slug = self.slug + "-" + re.sub(r"[/\.\\]+", "-", path.stem.strip("-"))
             self.uploaded_images[filename] = wp.upload_media(slug, path)
 
+    @property
+    def local_audio_references(self) -> set[str]:
+        """
+        Local audio files referenced by `::: audio <path>` directives.
+
+        >>> b = Blog()
+        >>> b.content = "## H\\n\\n::: audio images/clip.mp3\\n\\ntext\\n"
+        >>> sorted(b.local_audio_references)
+        ['images/clip.mp3']
+        """
+        return set(
+            filter(
+                lambda u: urlparse(u).scheme in ["", "file"],
+                map(
+                    lambda m: m.group("url"),
+                    re.finditer(self.audio_directive_pattern, self.content),
+                ),
+            )
+        )
+
+    def upload_local_audio(self, wp: Wordpress):
+        self.uploaded_audio = {}
+        for filename in self.local_audio_references:
+            path = Path(self.dir).joinpath(filename)
+            if not path.exists():
+                logging.warning("%s does not exist", path)
+                continue
+
+            slug = self.slug + "-" + re.sub(r"[/\.\\]+", "-", path.stem.strip("-"))
+            self.uploaded_audio[filename] = wp.upload_media(slug, path)
+
     def to_wordpress(self, wp: Wordpress) -> dict:
         author = wp.get_unique_user_by_name(self.author, self.email, self.author_id)
         self.upload_local_images(wp)
+        self.upload_local_audio(wp)
         result = {
             "title": self.title,
             "slug": self.slug,

src/wordpress_markdown_blog_loader/html_to_gutenberg.py

@@ -14,6 +14,10 @@ def _wrap_in_gutenberg_comments(element):
         return _wrap_list(element)
     if element.name == "img":
         return _wrap_image(element)
+    if element.name == "figure" and "wp-block-audio" in element.get("class", []):
+        return _wrap_audio(element)
+    if element.name == "audio":
+        return _wrap_audio(element)
     if element.name == "blockquote":
         return _wrap_quote(element)
     return str(element)
@@ -86,6 +90,24 @@ def _wrap_image(element):
     return f"<!-- wp:image -->\n{str(element)}\n<!-- /wp:image -->"
 
 
+def _wrap_audio(element):
+    """
+    Wrap an audio element in a wp:audio Gutenberg block. Accepts either a bare
+    <audio> tag or a <figure class="wp-block-audio"> already wrapping one, and
+    always emits the figure form Wordpress expects.
+
+    >>> from bs4 import BeautifulSoup
+    >>> soup = BeautifulSoup('<audio controls src="https://x/c.mp3"></audio>', "html.parser")
+    >>> _wrap_audio(soup.audio)
+    '<!-- wp:audio -->\\n<figure class="wp-block-audio"><audio controls="" src="https://x/c.mp3"></audio></figure>\\n<!-- /wp:audio -->'
+    """
+    audio = element if element.name == "audio" else element.find("audio")
+    figure = (
+        f'<figure class="wp-block-audio">{str(audio)}</figure>' if audio else str(element)
+    )
+    return f"<!-- wp:audio -->\n{figure}\n<!-- /wp:audio -->"
+
+
 def convert(title, html_body):
     soup = BeautifulSoup(html_body, "html.parser")
     blocks = []

tests/test_blog.py

@@ -15,5 +15,38 @@ def test_tables(self):
         self.assertIn('<tbody>', blog.rendered)
         self.assertIn('<td style="text-align: left;">Hello</td>', blog.rendered)
 
+
+class Test_AudioDirective(unittest.TestCase):
+    def _blog(self, content):
+        blog = Blog()
+        blog.title = "Audio post"
+        blog.content = content
+        return blog
+
+    def test_local_audio_references(self):
+        blog = self._blog(
+            "## One\n\n::: audio images/clips/a.mp3\n\ntext\n\n"
+            "## Two\n\n::: audio images/clips/b.wav\n\nmore\n"
+        )
+        self.assertEqual(
+            blog.local_audio_references,
+            {"images/clips/a.mp3", "images/clips/b.wav"},
+        )
+
+    def test_remote_audio_not_collected_as_local(self):
+        blog = self._blog("::: audio https://cdn.example.com/a.mp3\n")
+        self.assertEqual(blog.local_audio_references, set())
+
+    def test_rendered_directive_becomes_audio_block(self):
+        # without an uploaded URL it falls back to the raw path (local preview)
+        blog = self._blog("## Section\n\n::: audio images/clips/a.mp3\n\ntext\n")
+        rendered = blog.rendered
+        self.assertIn("<!-- wp:audio -->", rendered)
+        self.assertIn('<figure class="wp-block-audio">', rendered)
+        self.assertIn('src="images/clips/a.mp3"', rendered)
+        # the directive line must not leak through as a paragraph
+        self.assertNotIn("::: audio", rendered)
+
+
 if __name__ == '__main__':
     unittest.main()

tests/test_html_to_gutenberg.py

@@ -8,6 +8,7 @@
     _wrap_pre,
     _wrap_list,
     _wrap_image,
+    _wrap_audio,
     _wrap_in_gutenberg_comments,
     _wrap_quote,
     convert,
@@ -77,6 +78,31 @@ def test_wrap_image(self):
         self.assertIn('<img alt="desc" src="img.png"/>', res)
         self.assertTrue(res.endswith("<!-- /wp:image -->"))
 
+    def test_wrap_audio_from_bare_tag(self):
+        soup = BeautifulSoup(
+            '<audio controls src="https://x/c.mp3"></audio>', "html.parser"
+        )
+        res = _wrap_audio(soup.audio)
+        self.assertTrue(res.startswith("<!-- wp:audio -->"))
+        self.assertIn('<figure class="wp-block-audio">', res)
+        self.assertIn('src="https://x/c.mp3"', res)
+        self.assertIn("<audio", res)
+        self.assertTrue(res.endswith("<!-- /wp:audio -->"))
+
+    def test_wrap_audio_from_figure(self):
+        html = '<figure class="wp-block-audio"><audio controls src="https://x/c.mp3"></audio></figure>'
+        soup = BeautifulSoup(html, "html.parser")
+        res = _wrap_audio(soup.figure)
+        self.assertTrue(res.startswith("<!-- wp:audio -->"))
+        self.assertIn('<figure class="wp-block-audio">', res)
+        self.assertIn('src="https://x/c.mp3"', res)
+
+    def test_wrap_in_gutenberg_comments_routes_audio_figure(self):
+        html = '<figure class="wp-block-audio"><audio controls src="https://x/c.mp3"></audio></figure>'
+        soup = BeautifulSoup(html, "html.parser")
+        res = _wrap_in_gutenberg_comments(soup.figure)
+        self.assertTrue(res.startswith("<!-- wp:audio -->"))
+
     def test_wrap_in_gutenberg_comments_with_comment(self):
         comment = Comment(" a comment ")
         res = _wrap_in_gutenberg_comments(comment)
@@ -157,6 +183,18 @@ def test_convert_handles_multiple_elements(self):
         self.assertIn("<!-- wp:heading -->", result)
         self.assertIn("<!-- wp:code -->", result)
 
+    def test_convert_with_audio(self):
+        title = "Audio"
+        html_body = (
+            '<h2>Section</h2>'
+            '<figure class="wp-block-audio">'
+            '<audio controls src="https://x/c.mp3"></audio></figure>'
+        )
+        result = convert(title, html_body)
+        self.assertIn("<!-- wp:heading -->", result)
+        self.assertIn("<!-- wp:audio -->", result)
+        self.assertIn('<figure class="wp-block-audio">', result)
+
 
 if __name__ == "__main__":
     unittest.main()