From a9b7bd60b21afc9235a598d38e7ca6f22c4c79ee Mon Sep 17 00:00:00 2001
From: Ben Sturmfels <ben@sturm.com.au>
Date: Thu, 30 Apr 2020 11:38:44 +1000
Subject: [PATCH] subtitles: Add documentation, limit uploads to *.vtt files,
 only show for video [#5589].

---
 docs/source/index.rst                         | 11 ++++----
 mediagoblin/plugins/subtitles/README.rst      | 25 +++++++++++++++++++
 mediagoblin/plugins/subtitles/forms.py        |  7 ++++--
 .../subtitles/subtitle_media_block.html       |  2 +-
 mediagoblin/plugins/subtitles/views.py        |  6 +++--
 5 files changed, 41 insertions(+), 10 deletions(-)
 create mode 100644 mediagoblin/plugins/subtitles/README.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index fbc57154..b13968a5 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -55,14 +55,15 @@ Part 2: Core plugin documentation
 .. toctree::
    :maxdepth: 1
 
-   plugindocs/flatpagesfile
-   plugindocs/sampleplugin
-   plugindocs/trim_whitespace
-   plugindocs/raven
    plugindocs/basic_auth
+   plugindocs/flatpagesfile
+   plugindocs/ldap
    plugindocs/openid
    plugindocs/persona
-   plugindocs/ldap
+   plugindocs/raven
+   plugindocs/sampleplugin
+   plugindocs/subtitles
+   plugindocs/trim_whitespace
 
 
 Part 3: Plugin Writer's Guide
diff --git a/mediagoblin/plugins/subtitles/README.rst b/mediagoblin/plugins/subtitles/README.rst
new file mode 100644
index 00000000..c45b6c20
--- /dev/null
+++ b/mediagoblin/plugins/subtitles/README.rst
@@ -0,0 +1,25 @@
+================
+Subtitles plugin
+================
+
+This plugin enables text captioning of videos (though not yet audio). Once the
+plugin is enabled, you'll see a link to upload subtitles in `WebVTT format`_ as
+supported by the Video.js `Text Tracks`_ feature.
+
+.. _WebVTT format: https://en.wikipedia.org/wiki/WebVTT
+.. _Text Tracks: https://docs.videojs.com/docs/guides/text-tracks.html
+
+.. _subtitles-setup:
+
+Enabling the subtitles plugin
+=============================
+
+1. Add the following to your MediaGoblin .ini file in the ``[plugins]`` section::
+
+    [[mediagoblin.plugins.subtitles]]
+
+2. Run::
+
+    $ ./bin/gmg dbupdate
+
+3. Restart your MediaGoblin process.
diff --git a/mediagoblin/plugins/subtitles/forms.py b/mediagoblin/plugins/subtitles/forms.py
index de8ffbcd..acf2af31 100644
--- a/mediagoblin/plugins/subtitles/forms.py
+++ b/mediagoblin/plugins/subtitles/forms.py
@@ -16,14 +16,17 @@
 
 import wtforms
 
+from mediagoblin.tools.translate import lazy_pass_to_ugettext as _
+
 class CustomizeSubtitlesForm(wtforms.Form):
     subtitle = wtforms.TextAreaField(
         ('Subtitle'),
         [wtforms.validators.Optional()],
-        description=(""))
+        description=_('Subtitles in <a href="https://en.wikipedia.org/wiki/WebVTT" target="_blank">WebVTT format</a>'))
 
 class EditSubtitlesForm(wtforms.Form):
     subtitle_language = wtforms.StringField(
         'Language')
     subtitle_file = wtforms.FileField(
-        'File')
+        'File',
+        description=_('Subtitles in <a href="https://en.wikipedia.org/wiki/WebVTT" target="_blank">WebVTT format</a>'))
diff --git a/mediagoblin/plugins/subtitles/templates/mediagoblin/plugins/subtitles/subtitle_media_block.html b/mediagoblin/plugins/subtitles/templates/mediagoblin/plugins/subtitles/subtitle_media_block.html
index 7426c971..4d4a203b 100644
--- a/mediagoblin/plugins/subtitles/templates/mediagoblin/plugins/subtitles/subtitle_media_block.html
+++ b/mediagoblin/plugins/subtitles/templates/mediagoblin/plugins/subtitles/subtitle_media_block.html
@@ -17,7 +17,7 @@
 #}
 
 {% block subtitle_block %}
-{% if "video.html" in media.media_manager.display_template or "audio.html" in media.media_manager.display_template %}
+{% if "video.html" in media.media_manager.display_template %}
       {%- if media.subtitle_files|count %}
         <h3>{% trans %}Subtitles{% endtrans %}</h3>
         <ul>
diff --git a/mediagoblin/plugins/subtitles/views.py b/mediagoblin/plugins/subtitles/views.py
index 46b844af..e3375306 100644
--- a/mediagoblin/plugins/subtitles/views.py
+++ b/mediagoblin/plugins/subtitles/views.py
@@ -45,8 +45,10 @@ UNSAFE_MIMETYPES = [
 @user_may_delete_media
 @require_active_login
 def edit_subtitles(request, media):
-    allowed_extensions = ['aqt','gsub','jss','sub','ttxt','pjs','psb',
-                        'rt','smi','stl','ssf','srt','ssa','ass','usf','vtt','lrc']
+    # This was originally quite a long list of allowed extensions, but as far as
+    # I understand, Video.js only supports WebVTT format subtitles:
+    # https://docs.videojs.com/docs/guides/text-tracks.html
+    allowed_extensions = ['vtt']
     form = forms.EditSubtitlesForm(request.form)
 
     # Add any subtitles
-- 
2.25.1