atsphinx-audioplayerを使い、Sphinxドキュメント上でオーディオファイルの再生をサポートしましょう
成り行き感が強いものの個人的な潜在需要もあったので、またSphinx拡張を増やしました。
この記事は、日本語で書いた簡易的なリリースノートです。
何を作ったんですか？
atsphinx-audioplayerというSphinx拡張です。
大雑把に書くと、簡単なディレクティブやロールを書くと、HTML系のビルドに<audio>タグを出力します。
これを利用することで、特定ページに向けた読み上げコンテンツの埋め込みをしたり、
Sphinx製サイト内でラジオコンテンツの展開ができるようになります。
使い方
使い方は非常にシンプルです。
読みながら試す場合は、Sphinxドキュメント内で下記のようなファイル構造となるように準備してください。
+ /
+ conf.py
+ index.rst
+ talk.mp3
拡張の有効化
すでにPyPIに登録済みなので、あなたが普段使っている方法でライブラリのインストールをしてください。
インストール後は、conf.pyに拡張を追加しましょう。
extensions = [
# 他の拡張
...,
# 追加
"atsphinx.audioplayer",
]
オーディオ要素の追加
atsphinx-audioplayerは、段落出力になる「ディレクティブ」とインライン出力になる「ロール」のどちらの方法でもオーディオ要素を埋め込めるようになっています。
ディレクティブを使う場合は、下記のように ``.. audio::`` を書いて、
後ろにオーディオファイルのパスを指定してください。
.. audio:: talk.mp3
インラインの場合は、 ``:audio`` ロールを使いオーディオファイルを指定してください。
例えば、 :audio:`talk.mp3` のような記述になります。
ビルドする
基本的に、これだけ書けばビルド時に<audio>タグとして出力してくれます。
実物がドキュメントにあるので、リポジトリのソースを横に眺めてみましょう。
オプションとか
ディレクティブ側に限り、:nocontrols:というオプションがあります。
これを指定すると、<audio>タグからcontrols属性がなくなります。
「HTML/JS上で操作したいので<audio>はあったほうが良い」が「ユーザーに操作してほしくない」というエッジケースで効果があります。
展望
この時点で一息入れることになって、また手直しするかは未定です。
ただし、実装をしていて、対応しておくと良さそうなことがあるので、メモ書き扱いで残しておきます。
ビルド時におけるオーディオファイルの出力先が気にくわない
Sphinxはビルド時にドキュメントの相対パスとして管理している画像や動画ファイルは_imagesフォルダへコピーされる仕様となっています。
atsphinx-audioplayerはimageではないのですが、同じく_imagesフォルダ行きにしています。
これは、Sphinx自体が画像ファイルに関する扱いを特に決めていないのが理由です。
Sphinxのコアともいえるdocutilsがimage,figureディレクティブに動画対応した結果として、動画も_images送りになっているため、今回の挙動も正しいといえば正しいです。
とはいえ、名前にまつわる違和感は強いので、なるべくならどうにかしたいところです。
<audio>タグの外側にもうひと要素欲しい
ディレクティブにしてもロールにしても、ビルド時に出力されるのは<audio>タグのみとなっています。
一方でMDN内にある<audio>のページを参照すると、
figureをはじめとした「ドキュメント読者向けに提供されて欲しいタグ」がいくつかあることが分かります。
どこかのタイミングで、このあたりのタグの出力もできるディレクティブなどは作りたいですね。
SphinxでPodcast配信できるのでは？
記事の冒頭に「Sphinx製サイトでラジオコンテンツの配布が可能になるかも？」と言ったことを書いています。
例えば、この拡張+αをなんとかしたうえで、RSSフィードを生成する拡張を組み合わせることで、Podcastの体裁でコンテンツを配布することも狙えそうです。
とはいえ、需要があるかも分からないのとPodcast向けフィードに必要なルールをまだ知らないので、いずれまたとなりそうですが。
完全な余談
ドキュメントには実際にこのディレクティブとロールを使ったデモがあるのは前述のとおりです。
このデモのための音声ファイルを、2年ほど前に買ったVOICEPEAKで作成しています。
ついでに読み上げプロジェクトを管理する.vppファイルもリポジトリ内に保管しています。
いくつかの課題感はあるものの、雑利用にあたっては非常に気楽な運用ができました。
Discussion