June 2021 • N3F.com

Running isn’t the most enjoyable activity, but it’s great for burning calories. One of the best ways to cope is by listening to podcasts. Podcast apps are generally great and provide innovative features — like speeding up the playback (to get through the content quicker). Switching between podcasts and audiobooks becomes jarring after expecting many of the same behaviors, so I spent a weekend throwing together a quick application to create podcasts from local files.

It’s pushed to github (as open-source) and can be used for turning local mp3’s into deliverable podcast episodes. Use it to produce a podcast or publish audio files to the web.

Filecasted

It’s a simple app — it takes a list of files and creates an RSS (.xml) file. The RSS file can be hosted on something like AWS for general delivery. I threw it together using poetry/python, and development is started by:

pip install poetry
poetry install
poetry shell — the filecast command is now available.

$ filecast --help

Usage: filecast [OPTIONS] INPUT

  Create a podcast file from INPUT.

  INPUT can be a playlist (`.m3u`), stdin (`-`), a directory or a collection
  of audio files.  Playlists and stdin should be a simple text document with
  a list of files to add.

Options:
  --version
  -v, --verbose
  -f, --force             Force the output to an existing file.
  --audio-extensions EXT  Comma separated list of processable extensions.
                          [default: .mp3,.mp4,.wav]

  -a, --append            Append INPUT to the output file.
  -o, --output PATH
  -n, --dry-run           Run as normally, but don't make any permanent
                          changes

  --help                  Show this message and exit.

It’s still a bit buggy. For instance, the album art doesn’t show correctly in the podcasts app I use, and some of the audio files downloaded strangely (but I don’t believe that was related to my code).

Also, there is a lot of room for improvement. It would be nice to manage some of the metadata and update/change feeds as needed. Or maybe support transcoding/speeding files up/adding/editing/splicing the audio files… Or adding support for awscli and delivering both the “episodes” and the RSS file to their space on the internet.

The sad ending

Despite the bugs, Filecasted worked for me in the limited capacity that I needed it to. I was able to create podcasts from local files, publish to AWS and then listen to it with my podcast app. Since I last used it though, I switched to Pocket Casts, which has a feature to play local files without the intermediate steps needed to host and download.

So the bugs will likely remain and I’ll just keep the joyful memory of building and using my creation 😢.

I get confused by a lot of words. The combination of complex ideas and large walls of text short-circuit and crash my brain. I’ll have to read and re-read a text-only passage multiple times to understand exactly what’s being described. Speaking presentations exacerbate the issue.

However the adage “A picture is worth a thousand words” definitely applies to me. Given graphical clues demonstrating the principle helps me begin to make connections and jumpstarting my understanding.

graph TD
   start(Explain an idea) -->|with words|start
   start --> |with pictures| understanding

One of the tools I’ve found very helpful (if only for myself) is MermaidJS. This software lets you create several different types of charts using a markdown-ish syntax. For instance, the above chart was created with:

graph TD
   start(Explain an idea) --> |with words| start
   start --> |with pictures| understanding

This grants other benefits in addition to the quicker comprehension. Quick edits to the text automatically recreates the chart without requiring any manual intervention/tweaking to the rest of the diagram.

MermaidJS supports flowcharts, sequence diagrams, class diagrams, state diagrams, ERD (entity-relationship diagrams), Gantt charts, pie charts, requirement diagrams and User Journey diagrams.

On my last post I actually used it to show the sequence of flows between WordPress, WooCommerce and webhooks.

WordPress Plugins

Working at Automattic, all our internal documentation and institutional knowledge is recorded using WordPress (you should really checkout using p2’s — it’s an awesome tool). Using Mermaid in this environment has been fantastic — Mermaid can be supported anywhere you have HTML (and I can be exported to SVG too), but as WordPress is running 40% of the web, this seems like a pretty good place to start.

In fact MermaidJS has a page dedicated to integrations of their software and mention a couple plugins:

WordPress Markdown Editor (seems to have been rebranded to WP Githuber-MD — see below)
WP-ReliableMD: The page was in a different language than I understand and I made a snap decision to avoid it 😢. Should I revisit this decision?

Here is my un-asked for 2¢ about some different WordPress plugins supporting MermaidJS.

WP Mermaid (and WP Githuber-MD)

These plugins are both created & maintained by Terry Lin. I think they’re both great. They support Gutenberg blocks. They display the Mermaid text. Give them a shot and see if they float your boat.

Personally, I didn’t need the full markdown editor, and WP Mermaid had a couple small annoyances that I couldn’t solve. I submitted a couple PR’s, but decided I could use something a little simpler, which brings me to my own plugin…

MerPress

I can’t take full credit for this plugin. My coworker Michael Pretty actually did most of the work on this iteration and I submitted it to WordPress.org. I’m giving him full-credit. He did an awesome job with it.

A couple features I really like:

MerPress keeps the wptexturize functionality. Posts preserve the capability to convert simple characters like quotes and dashes into the nice curly quotes and dashes (e.g. “”, –, —).
In the Gutenberg editor, the block is encased in a code block letting you edit the code with a monotype font.

Some features I would like to see:

Ability to change the theme site-wide and per block
Add other configuration parameters to the block
Support 3rd party CDN (something that WP Mermaid already does)

Conclusion

If you learned nothing else, you now know I need pictures in order to comprehend complex concepts. Hopefully it’s also obvious that Mermaid is a neat tool and can be used to quickly share intention and purpose and thoughts without all the words.

graph TD
  ad(all done) --> te(the end)

Please let me know if I’m missing a plugin that I should try or if there is something you would like to see added to MerPress…