branch: elpa/subed
commit df6f443ac6ed4c02bacb64a3f1c5c7888dfca5d0
Author: Sacha Chua <sa...@sachachua.com>
Commit: Sacha Chua <sa...@sachachua.com>
v1.2.25: Bump version and add docs
---
NEWS.org | 14 +++++++
README.org | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
subed/subed.el | 2 +-
3 files changed, 138 insertions(+), 2 deletions(-)
diff --git a/NEWS.org b/NEWS.org
index 7e76a17062..31a82f4ed4 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -2,6 +2,20 @@
* subed news
+** Version 1.2.25 - 2025-01-28 - Sacha Chua
+
+- subed-vtt: Don't require blank lines before timestamps. Support multiple
components in a cue.
+- Document YouTube workflow.
+
+** Version 1.2.24 - 2025-01-24 - Sacha Chua
+
+- New command subed-section-comments-as-chapters.
+- subed-word-data.el: Load word data from Youtube VTT files.
+- Approximately match word data.
+- Move CPS overlay more often.
+- subed-sum-time can take a list of subtitles.
+- subed-vtt merges comments as well.
+
** Version 1.2.23 - 2024-12-19 - Sacha Chua
- New menu.
diff --git a/README.org b/README.org
index dde81d7b7c..bb89520389 100644
--- a/README.org
+++ b/README.org
@@ -5,6 +5,9 @@ SPDX-License-Identifier: GPL-3.0-or-later
#+END_COMMENT
* subed
+:PROPERTIES:
+:CUSTOM_ID: subed
+:END:
subed is an Emacs major mode for editing subtitles while playing the
corresponding media file with [[https://mpv.io/][mpv]]. At the moment, the
only supported
formats are:
@@ -23,6 +26,9 @@ formats are:
[[file:word-data-and-waveform.png]]
** Features
+:PROPERTIES:
+:CUSTOM_ID: subed-features
+:END:
- Jump to next (~M-n~) and previous (~M-p~) subtitle text.
- Jump to the beginning (~C-M-a~) and end (~C-M-e~) of the current
@@ -90,6 +96,9 @@ formats are:
with an audio file in order to get timestamps.
*** mpv integration (optional)
+:PROPERTIES:
+:CUSTOM_ID: subed-features-mpv-integration-optional
+:END:
Using network sockets to control MPV works on Linux and on Mac OS X,
but not on Microsoft Windows due to the lack of Unix-style sockets. On
@@ -119,7 +128,13 @@ Microsoft Windows, you will not be able to synchronize
with MPV.
key is pressed).
** Installation
+:PROPERTIES:
+:CUSTOM_ID: subed-installation
+:END:
*** Installing the subed package from NonGNU Elpa
+:PROPERTIES:
+:CUSTOM_ID: subed-installation-installing-the-subed-package-from-nongnu-elpa
+:END:
~subed~ is now on [[https://elpa.nongnu.org/nongnu/subed.html][NonGNU ELPA]].
On Emacs 28 and later, you can install it with ~M-x package-install~ ~subed~.
To install it on Emacs 27 or earlier, add the following to your Emacs
configuration file:
@@ -155,6 +170,9 @@ Sample configuration:
#+end_src
*** Manual installation
+:PROPERTIES:
+:CUSTOM_ID: subed-installation-manual-installation
+:END:
If that doesn't work, you can install it manually. To install from the main
branch:
@@ -218,6 +236,9 @@ following command inside the =subed= directory:
git checkout branchname
#+end_src
*** use-package configuration
+:PROPERTIES:
+:CUSTOM_ID: subed-installation-use-package-configuration
+:END:
Here's an example setup if you use
[[https://github.com/jwiegley/use-package][use-package]]:
@@ -247,6 +268,9 @@ Here's an example setup if you use
[[https://github.com/jwiegley/use-package][us
#+END_SRC
*** straight configuration
+:PROPERTIES:
+:CUSTOM_ID: subed-installation-straight-configuration
+:END:
If you use [[https://github.com/radian-software/straight.el][straight.el]],
you can install subed with the following recipe:
@@ -255,14 +279,22 @@ If you use
[[https://github.com/radian-software/straight.el][straight.el]], you
#+end_src
** Getting started
+:PROPERTIES:
+:CUSTOM_ID: subed-getting-started
+:END:
~C-h f subed-mode~ should get you started. This is the parent mode for
~subed-srt-mode~, ~subed-vtt-mode~, and ~subed-ass-mode~. When
manually loading a mode, use those specific format modes instead of
~subed-mode~.
** Some workflow ideas
-
+:PROPERTIES:
+:CUSTOM_ID: subed-some-workflow-ideas
+:END:
*** Editing subtitles
+:PROPERTIES:
+:CUSTOM_ID: subed-some-workflow-ideas-editing-subtitles
+:END:
You can use ~subed-mpv-jump-to-current-subtitle~ (~M-j~) to play the current
subtitle and use ~subed-mpv-toggle-pause~ (~M-SPC~) to stop at the right time.
@@ -274,6 +306,9 @@ If you have wdiff installed, you can use
with a script or another subtitle file.
*** Writing subtitles from scratch
+:PROPERTIES:
+:CUSTOM_ID: subed-some-workflow-ideas-writing-subtitles-from-scratch
+:END:
One way is to start with one big subtitle that covers the whole media
file. You can create this manually by using the media file duration or a very
large ending timestamp (ex: 24:00:000), or you can use ~M-x
subed-insert-subtitle-for-whole-file~.
@@ -283,7 +318,52 @@ Another way is to type as much of the text as you can
without worrying
about timestamps, putting each caption on a separate line. Then you
can use ~subed-align~ to convert it into timestamped captions.
+*** Starting from auto-generated YouTube captions
+:PROPERTIES:
+:CUSTOM_ID:
subed-some-workflow-ideas-starting-from-auto-generated-youtube-captions
+:END:
+
+To download autogenerated captions for one of the
+videos you've uploaded to YouTube:
+
+1. Go to https://studio.youtube.com
+2. Click on Content in the left-side menu, find your video, and edit it.
Clicok on Subtitles in the left menu. If automatic subtitles are available, you
will see them in the Subtitles column in the middle.
+ - If you don't see automatic subtitles, set
+ your video's language in the Details tab,
+ wait a while, and check again.
+3. Hover over the "Published" label and use the
+ three-dot menu to download the SRT. (The VTT
+ file has a lot of extra mark-up.)
+4. Open the SRT file. subed can synchronize
+ playback as you edit the subtitle file. If the
+ media has the same base filename as the
+ subtitle file, it will be opened automatically.
+ If not, use ~subed-mpv-play-from-file~ (~C-c
+ C-v~) or ~subed-mpv-play-from-url~ (~C-c C-u~).
+
+You may want to use ~M-x subed-trim-overlaps~ to remove the overlaps between
subtitles.
+
+If you download the VTT from YouTube, you can load
+the word timing data from it with ~M-x
+subed-word-data-load-from-file~. Then those times
+will be used when splitting subtitles with
+~subed-split-subtitle~..
+
+If you want to work in the VTT format so you can
+use comments, convert the SRT with ~M-x
+subed-convert~.
+
+To upload edited subtitles:
+
+1. Edit your video's details. Click on Subtitles on the right side.
+2. Click on the three-dot menu.
+3. Click on "Upload file", choose "With timing", and click on "Continue".
+4. Select your file.
+
*** Reflowing subtitles into shorter or longer lines
+:PROPERTIES:
+:CUSTOM_ID:
subed-some-workflow-ideas-reflowing-subtitles-into-shorter-or-longer-lines
+:END:
You may want to use ~set-fill-column~ and
~display-fill-column-indicator-mode~ to show the target number of
@@ -301,6 +381,9 @@ want to keep looping. ~subed-waveform-show-current~ can
help you
fine-tune the split.
*** Adjusting timestamps
+:PROPERTIES:
+:CUSTOM_ID: subed-some-workflow-ideas-adjusting-timestamps
+:END:
You can use ~subed-mpv-jump-to-current-subtitle~ (~M-j~) to play the
current subtitle manually. Use
@@ -326,6 +409,9 @@ use a millisecond offset instead, use
~subed-shift-subtitles~.
**** Waveforms
+:PROPERTIES:
+:CUSTOM_ID: subed-some-workflow-ideas-adjusting-timestamps-waveforms
+:END:
Use ~subed-waveform-show-current~ or ~subed-waveform-show-all~ together with
FFmpeg
to display waveforms for subtitles.
@@ -343,6 +429,9 @@ subtitles as well.
You can use ~M-mouse-2~ (Meta-middle-click, ~subed-waveform-shift-subtitles~)
to shift the current subtitle and succeeding subtitles so that they start at
the position you clicked on.
**** A transient map for retiming subtitles
+:PROPERTIES:
+:CUSTOM_ID:
subed-some-workflow-ideas-adjusting-timestamps-a-transient-map-for-retiming-subtitles
+:END:
You can use ~subed-retime-subtitles~ to set new
times for subtitles by pressing ~SPC~ when the
@@ -359,6 +448,9 @@ Keys:
| ~p~ | pause |
**** Aeneas forced alignment tool
+:PROPERTIES:
+:CUSTOM_ID:
subed-some-workflow-ideas-adjusting-timestamps-aeneas-forced-alignment-tool
+:END:
The [[https://www.readbeyond.it/aeneas/][aeneas forced alignment tool]]
(Python) can take
a media file and a text file (one cue per line) or
@@ -394,6 +486,9 @@ quickly verify if the subtitle times are
reasonable.
**** Word timing data
+:PROPERTIES:
+:CUSTOM_ID: subed-some-workflow-ideas-adjusting-timestamps-word-timing-data
+:END:
To use word timing data from something like
WhisperX, load subed-word-data.el and then use
@@ -402,6 +497,9 @@ will then be used when you split subtitles with
~subed-split-subtitle~.
*** Exporting text for review
+:PROPERTIES:
+:CUSTOM_ID: subed-some-workflow-ideas-exporting-text-for-review
+:END:
You can use ~subed-copy-region-text~ to copy the text of the subtitles
for pasting into another buffer. Call it with the universal prefix
@@ -410,7 +508,13 @@ for pasting into another buffer. Call it with the
universal prefix
You can also use ~subed-convert~ to convert subtitles to a text file.
** Troubleshooting
+:PROPERTIES:
+:CUSTOM_ID: subed-troubleshooting
+:END:
*** subed-mpv: Service name too long
+:PROPERTIES:
+:CUSTOM_ID: subed-troubleshooting-subed-mpv-service-name-too-long
+:END:
If =subed-mpv-client= reports =(error "Service name too long")=, this
is probably because the path to the socket used to communicate with
@@ -418,6 +522,9 @@ MPV is too long for your operating system. You can use =M-x
customize=
to set =subed-mpv-socket-dir= to a shorter path.
** Important change in v1.0.0
+:PROPERTIES:
+:CUSTOM_ID: subed-important-change-in-v1-0-0
+:END:
~subed~ now uses ~subed-srt-mode~, ~subed-vtt-mode~, and
~subed-ass-mode~ instead of directly using ~subed-mode~. These modes
@@ -436,10 +543,16 @@ of ~subed-mode~. The specific backend functions (ex:
using generic functions such as ~subed-jump-to-subtitle-id~.
** Testing
+:PROPERTIES:
+:CUSTOM_ID: subed-testing
+:END:
You'll need to install the =buttercup= and =package-lint= Emacs packages.
You'll also need =GNU Make= so that you can work with Makefiles. To run the
tests, use the command =make test=.
** Contributions
+:PROPERTIES:
+:CUSTOM_ID: subed-contributions
+:END:
Contributions would be really appreciated! subed conforms to the
[[https://reuse.software/spec/][REUSE
Specification]]; this means that every file has copyright and license
information. If you modify a file, please update the year shown after
@@ -450,6 +563,9 @@ You'll need to install the =buttercup= and =package-lint=
Emacs packages. You'll
address if you like) to the list.
** License
+:PROPERTIES:
+:CUSTOM_ID: subed-license
+:END:
subed is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
@@ -460,6 +576,9 @@ You'll need to install the =buttercup= and =package-lint=
Emacs packages. You'll
FOR A PARTICULAR PURPOSE. See the
[[https://www.gnu.org/licenses/gpl-3.0.txt][GNU General Public License]] for
more
details.
* Build tips
+:PROPERTIES:
+:CUSTOM_ID: build-tips
+:END:
Here's a post-commit hook that will make it easier to remember to tag releases:
@@ -499,6 +618,9 @@ else:
#+end_src
* Other resources
+:PROPERTIES:
+:CUSTOM_ID: other-resources
+:END:
-
[[https://rodrigo.morales.pe/2024/11/17/my-subed-configuration-for-adding-subtitles-to-emacsconf-2024/][My
subed customizations for editing captions of Emacsconf 2024 – Rodrigo Morales]]
- [[https://sachachua.com/blog/category/subed][Sacha Chua's subed-related blog
posts]]
diff --git a/subed/subed.el b/subed/subed.el
index 5e3f048fdd..8bd86b0d8c 100644
--- a/subed/subed.el
+++ b/subed/subed.el
@@ -1,6 +1,6 @@
;;; subed.el --- A major mode for editing subtitles -*- lexical-binding: t;
-*-
-;; Version: 1.2.24
+;; Version: 1.2.25
;; Maintainer: Sacha Chua <sa...@sachachua.com>
;; Author: Random User
;; Keywords: convenience, files, hypermedia, multimedia
