[nongnu] elpa/subed 573a137e45: New commands for merging subtitles in a region, bugfixes

[ELPA Syncer]

branch: elpa/subed
commit 573a137e45feeef001d8ddafc71b5b35b28db3f5
Author: Sacha Chua <sacha@sachachua.com>
Commit: Sacha Chua <sacha@sachachua.com>

    New commands for merging subtitles in a region, bugfixes
    
    * subed/subed-common.el (set-subtitle-text): New command.
    (subed-merge-dwim): New command.
    (subed-merge-region): New command.
    (merge-region-and-set-text): New command.
    (subed-save-excursion): Clear the correct timer.
    * subed/subed-align.el (subed-align): Delete temp file only if used.
    * subed/subed-vtt.el (subed--append-subtitle): Insert newline when needed.
    * subed/subed.el (subed-mode-map): Use subed-merge-dwim.
    * tests/test-subed-common.el ("Setting subtitle"): Add tests.
    ("Merging a region"): Add tests.
    ("Merging a region and setting the text"): Add tests.
---
 NEWS.org                   |  10 ++++
 README.org                 | 142 +++++++++++++++++++++++++--------------------
 subed/subed-align.el       |   2 +-
 subed/subed-common.el      |  41 ++++++++++++-
 subed/subed-vtt.el         |   4 +-
 subed/subed.el             |   4 +-
 tests/test-subed-common.el | 120 ++++++++++++++++++++++++++++++++++++++
 7 files changed, 253 insertions(+), 70 deletions(-)

diff --git a/NEWS.org b/NEWS.org
index 8baa7a5d32..5464719584 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -1,6 +1,16 @@
 #+OPTIONS: toc:nil
 
 * subed news
+** Version 1.0.19 - 2022-11-11 - Sacha Chua
+
+New commands subed-merge-dwim, subed-merge-region,
+subed-merge-region-and-set-text, and set-subtitle-text can help with
+making chapter files.
+
+Added more details to the README.org.
+
+This version also includes bugfixes for subed-align and subed-vtt.
+
 ** Version 1.0.18 - 2022-11-08 - Sacha Chua
 
 New function subed-parse-file.
diff --git a/README.org b/README.org
index b09d4701cf..b79ff50a10 100644
--- a/README.org
+++ b/README.org
@@ -15,78 +15,92 @@ corresponding video with [[https://mpv.io/][mpv]].  At the 
moment, the only supp
   it's a common data format, but you can use ~subed-tsv-mode~ to turn
   it on in a buffer.
 
-[[file:https://raw.githubusercontent.com/rndusr/subed/master/screenshot.jpg]]
+[[file:https://raw.githubusercontent.com/sachac/subed/master/screenshot.jpg]]
 
 ** Features
-   - Quickly jump to next (~M-n~) and previous (~M-p~) subtitle text.
-   - Quickly jump to the beginning (~C-M-a~) and end (~C-M-e~) of the current
-     subtitle's text.
-   - Insert subtitles evenly spaced throughout the available space (~M-i~) or
-     right next the current subtitle (~C-M-i~).  A prefix argument controls how
-     many subtitles to insert and whether they are inserted before or after the
-     current subtitle.
-   - Kill subtitles (~M-k~).
-   - Adjust subtitle start (~M-[~ / ~M-]~) and stop (~M-{~ / ~M-}~) time.  A
-     prefix argument sets the number of milliseconds for the current session
-     (e.g. ~C-u 1000 M-[ M-[ M-[~ decreases start time by 3 seconds).
-   - Move the current subtitle or all marked subtitles forward (~C-M-n~) or
-     backward (~C-M-p~) in time without changing subtitle duration.  A prefix
-     argument sets the number of milliseconds for the current session (e.g. 
~C-u
-     500 C-M-n C-M-n~ moves the current subtitle 1 second forward).
-   - Shift the current subtitle forward (~C-M-f~) or backward (~C-M-b~) 
together
-     with all following subtitles.  This is basically a convenience shortcut 
for
-     ~C-SPC M-> C-M-n/p~.
-   - Scale all subtitles or all marked subtitles forward (~C-M-x~) or backward
-     (~C-M-S-x~) in time without changing subtitle duration.  A prefix argument
-     sets the number of milliseconds for the current session (e.g. ~C-u 500
-     C-M-x~ moves the last [or last marked] subtitle forward 500ms and
-     proportionally scales all [or all marked] subtitles based on this time
-     extension.  Similarly, ~C-u 500 C-M-S-x~ moves the last [or last marked]
-     subtitle backward 500ms and proportionally scales all [or all marked]
-     subtitles based on this time contraction).  This can be extremely useful 
to
-     correct synchronization issues in existing subtitle files.  First, adjust
-     the starting time if necessary (e.g. ~C-M-f~), then adjust the ending and
-     scale constituent subtitles (e.g. ~C-M-x~).
-   - Show CPS (characters per second) for the current subtitle.
-   - Insert HTML-like tags (~C-c C-t C-t~, with an optional attribute
-     when prefixed by ~C-u~), in particular italics (~C-c C-t C-i~) or
-     boldface (~C-c C-t C-b~).
-   - Sort and re-number subtitles and remove any extra spaces and newlines
-     (~M-s~).  This is done automatically every time the buffer is saved.
-   - Trim subtitle overlaps with ~M-x subed-trim-overlaps~. By
-     default, this adjusts the stop time of overlapping subtitles to
-     ~subed-subtitle-spacing~ milliseconds before the next subtitle
-     starts. Use ~M-x customize-group~ ~subed~ to configure trimming
-     to happen automatically when buffers are loaded or saved, which
-     time is adjusted, and how much time to leave between subtitles.
-   - Convert between formats with ~M-x subed-convert~.
-     
+
+- 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
+  subtitle's text.
+- Merge subtitles with ~M-m~ (~subed-merge-dwim~) and split them with
+  ~M-.~ (~subed-split-subtitle~). If the media file is playing in MPV,
+  use the current playback position. If not, use the relative position
+  in the subtitle text, or other functions listed in
+  ~subed-split-subtitle-timestamp-functions~.
+- Insert subtitles evenly spaced throughout the available space (~M-i~) or
+  right next to the current subtitle (~C-M-i~).  A prefix argument controls how
+  many subtitles to insert and whether they are inserted before or after the
+  current subtitle.
+- Kill subtitles (~M-k~).
+- Adjust subtitle start (~M-[~ / ~M-]~) and stop (~M-{~ / ~M-}~) time.  A
+  prefix argument sets the number of milliseconds for the current session
+  (e.g. ~C-u 1000 M-[ M-[ M-[~ decreases start time by 3 seconds).
+- Move the current subtitle or all marked subtitles forward (~C-M-n~) or
+  backward (~C-M-p~) in time without changing subtitle duration.  A prefix
+  argument sets the number of milliseconds for the current session (e.g. ~C-u
+  500 C-M-n C-M-n~ moves the current subtitle 1 second forward).
+- Shift the current subtitle forward (~C-M-f~) or backward (~C-M-b~) together
+  with all following subtitles.  This is basically a convenience shortcut for
+  ~C-SPC M-> C-M-n/p~.
+- Scale all subtitles or all marked subtitles forward (~C-M-x~) or backward
+  (~C-M-S-x~) in time without changing subtitle duration.  A prefix argument
+  sets the number of milliseconds for the current session (e.g. ~C-u 500
+  C-M-x~ moves the last [or last marked] subtitle forward 500ms and
+  proportionally scales all [or all marked] subtitles based on this time
+  extension.  Similarly, ~C-u 500 C-M-S-x~ moves the last [or last marked]
+  subtitle backward 500ms and proportionally scales all [or all marked]
+  subtitles based on this time contraction).  This can be extremely useful to
+  correct synchronization issues in existing subtitle files.  First, adjust
+  the starting time if necessary (e.g. ~C-M-f~), then adjust the ending and
+  scale constituent subtitles (e.g. ~C-M-x~).
+- Show CPS (characters per second) for the current subtitle.
+- Insert HTML-like tags (~C-c C-t C-t~, with an optional attribute
+  when prefixed by ~C-u~), in particular italics (~C-c C-t C-i~) or
+  boldface (~C-c C-t C-b~).
+- SRT: Sort and re-number subtitles and remove any extra spaces and
+  newlines (~M-s~). This is done automatically every time the buffer
+  is saved.
+- Trim subtitle overlaps with ~M-x subed-trim-overlaps~. By
+  default, this adjusts the stop time of overlapping subtitles to
+  ~subed-subtitle-spacing~ milliseconds before the next subtitle
+  starts. Use ~M-x customize-group~ ~subed~ to configure trimming
+  to happen automatically when buffers are loaded or saved, which
+  time is adjusted, and how much time to leave between subtitles.
+- Convert between formats with ~M-x subed-convert~.
+- Load word timing data (ex: SRV2) using ~M-x
+  subed-word-data-load-from-file~.
+- Use ~M-x subed-align~ and [[https://www.readbeyond.it/aeneas/][aeneas]] to 
align your text or subtitles
+  with an audio file in order to get timestamps.
+  
 *** mpv integration (optional)
 
 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
 Microsoft Windows, you will not be able to synchronize with MPV.
 
-   - Open videos with ~C-c C-v~ or automatically when opening a subtitle file 
if the
-     video file is named like the subtitle file but with a video extension
-     (e.g. ~.mkv~ or ~.avi~).
-   - Subtitles are automatically reloaded in mpv when the buffer is saved.
-   - Cursor and playback position are synchronized:
-     - Playback in mpv seeks to the position of the current subtitle as the
-       cursor moves between subtitles (~C-c ,~).
-     - The cursor is moved to the currently relevant subtitle as the video is
-       playing (~C-c .~).
-   - Copy the current playback position as start (~C-c [~) or stop (~C-c ]~)
-     time of the current subtitle.
-   - Playback is paused or slowed down when a subtitle's text is edited (~C-c
-     C-p~).
-   - Loop over the current subtitle in mpv (~C-c C-l~).
-   - When a subtitle's start or stop time changes, mpv seeks to the subtitle's
-     start time (~C-c C-r~).
-   - Pause video playback without leaving Emacs (~M-SPC~).
-   - Move one frame forward or backward (~C-c C-f .~ and ~C-c C-f ,~;
-     pressing ~,~ or ~.~ afterwards moves by frames until any other
-     key is pressed).
+- Automatically open the associated media file in MPV based on the filename, 
open a media file manually with ~C-c C-v~ (~subed-mpv-find-video~), or play 
media directly from a URL with ~C-c C-u~ (~subed-mpv-play-video-from-url~) .
+  This works for audio files as well.
+- Pause and resume video playback without leaving Emacs (~M-SPC~).
+- Jump to the current subtitle in the MPV player with ~M-j~
+  (~subed-mpv-jump-to-current-subtitle~). Toggle looping over the
+  current subtitle with ~C-c C-l~
+  (~subed-toggle-loop-over-current-subtitle~).  Control how many seconds
+  to loop before or after the current subtitles by customizing
+  ~subed-loop-seconds-before~ and ~subed-loop-seconds-after~.
+- Use
+  ~C-c .~ (~subed-toggle-sync-point-to-player~) to toggle whether the point 
should move to the currently playing subtitle.
+- Use ~C-c ,~ (~subed-toggle-sync-player-to-point~) to toggle whether mpv 
should seek to the position of the current subtitle when the point moves 
between subtitles.
+- Subtitles are automatically reloaded in mpv when the buffer is saved.
+- Copy the current playback position as start (~C-c [~) or stop (~C-c ]~)
+  time of the current subtitle.
+- Playback is paused or slowed down when a subtitle's text is edited (~C-c
+  C-p~, ~subed-toggle-pause-while-typing~).
+- Loop over the current subtitle in mpv (~C-c C-l~).
+- When a subtitle's start or stop time changes, mpv seeks to the subtitle's
+  start time (~C-c C-r~, ~subed-toggle-replay-adjusted-subtitle~).
+- Move one frame forward or backward (~C-c C-f .~ and ~C-c C-f ,~;
+  pressing ~,~ or ~.~ afterwards moves by frames until any other
+  key is pressed).
 
 ** Installation
 *** Installing the subed package from NonGNU Elpa
diff --git a/subed/subed-align.el b/subed/subed-align.el
index d1b7e873ca..6e3871d076 100644
--- a/subed/subed-align.el
+++ b/subed/subed-align.el
@@ -71,7 +71,7 @@ Return a buffer with FORMAT."
                                  "subtitles"
                                "plain"))
                      new-file)))
-      (delete-file temp-file)
+      (when temp-file (delete-file temp-file))
       (find-file new-file)
       (when (string= format "VTT")
         (goto-char (point-min))
diff --git a/subed/subed-common.el b/subed/subed-common.el
index 3c7619f091..ce0ff90663 100644
--- a/subed/subed-common.el
+++ b/subed/subed-common.el
@@ -240,6 +240,15 @@ If SUB-ID is not given, use subtitle on point."
           (when (and beg end)
             (buffer-substring beg end)))) ""))
 
+(subed-define-generic-function set-subtitle-text (text &optional sub-id)
+  "Set subtitle text to TEXT.
+
+If SUB-ID is not given, set the text of the current subtitle."
+  (interactive "MNew text: ")
+  (subed-jump-to-subtitle-text sub-id)
+  (delete-region (point) (or (subed-jump-to-subtitle-end) (point)))
+  (insert text))
+
 (subed-define-generic-function subtitle-relative-point ()
   "Point relative to subtitle's ID or nil if ID can't be found."
   (let ((start-point (save-excursion
@@ -390,7 +399,7 @@ scheduled call is canceled and another call is scheduled in
 100ms."
   (interactive)
   (when subed--regenerate-ids-soon-timer
-    (cancel-timer subed-srt--regenerate-ids-soon-timer))
+    (cancel-timer subed--regenerate-ids-soon-timer))
   (setq subed--regenerate-ids-soon-timer
         (run-at-time 0.1 nil (lambda ()
                                (setq subed--regenerate-ids-soon-timer nil)
@@ -1226,6 +1235,15 @@ position of the point."
 
 ;;; Merging
 
+(defun subed-merge-dwim ()
+  "Merge the subtitles in the region if the region is active.
+If the region is not active, merge the current subtitle with the next one."
+  (interactive)
+  (if (region-active-p)
+      (subed-merge-region (min (point) (mark))
+                          (max (point) (mark)))
+    (subed-merge-with-next)))
+
 (subed-define-generic-function merge-with-next ()
   "Merge the current subtitle with the next subtitle.
 Update the end timestamp accordingly."
@@ -1239,6 +1257,27 @@ Update the end timestamp accordingly."
       (subed-merge-with-next)
     (error "No previous subtitle to merge into")))
 
+(subed-define-generic-function merge-region (beg end)
+  "Merge the subtitles in the region defined by BEG and END."
+  (interactive "r")
+  (save-restriction
+    (narrow-to-region (progn (goto-char beg) (or (subed-jump-to-subtitle-id) 
(point)))
+                      (progn (goto-char end) (or (subed-jump-to-subtitle-end) 
(point))))
+    (goto-char beg)
+    (while (save-excursion (subed-forward-subtitle-id))
+      (subed-merge-with-next))))
+
+(subed-define-generic-function merge-region-and-set-text (beg end text)
+  "Merge the subtitles in the region defined by BEG and END.
+Replace the subtitle text with TEXT.  If the region is not
+specified, set the current subtitle's text."
+  (interactive (list (when (region-active-p) (min (point) (mark)))
+                     (when (region-active-p) (max (point) (mark)))
+                     (read-string "Text: ")))
+  (when (and beg end)
+    (subed-merge-region beg end))
+  (subed-set-subtitle-text text))
+
 ;;; Replay time-adjusted subtitle
 
 (defun subed-replay-adjusted-subtitle-p ()
diff --git a/subed/subed-vtt.el b/subed/subed-vtt.el
index 8b587cae83..6dd8842775 100644
--- a/subed/subed-vtt.el
+++ b/subed/subed-vtt.el
@@ -275,8 +275,8 @@ point.  Use the format-specific function for MAJOR-MODE."
     ;; Move to end of separator
     (goto-char (match-end 0)))
   (insert (subed-make-subtitle id start stop text))
-  ;; Complete separator with another newline unless we inserted at the end
-  (when (looking-at (concat "\\([[:space:]]*\\|^\\)" subed--regexp-timestamp))
+  (unless (eolp)
+    ;; Complete separator with another newline unless we inserted at the end
     (insert ?\n))
   (forward-line -2)
   (subed-jump-to-subtitle-text))
diff --git a/subed/subed.el b/subed/subed.el
index 05e693b85a..c27a8c2db2 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.0.18
+;; Version: 1.0.19
 ;; Maintainer: Sacha Chua <sacha@sachachua.com>
 ;; Author: Random User
 ;; Keywords: convenience, files, hypermedia, multimedia
@@ -65,7 +65,7 @@
     (define-key subed-mode-map (kbd "M-i") #'subed-insert-subtitle)
     (define-key subed-mode-map (kbd "C-M-i") #'subed-insert-subtitle-adjacent)
     (define-key subed-mode-map (kbd "M-k") #'subed-kill-subtitle)
-    (define-key subed-mode-map (kbd "M-m") #'subed-merge-with-next)
+    (define-key subed-mode-map (kbd "M-m") #'subed-merge-dwim)
     (define-key subed-mode-map (kbd "M-M") #'subed-merge-with-previous)
     (define-key subed-mode-map (kbd "M-.") #'subed-split-subtitle)
     (define-key subed-mode-map (kbd "M-s") #'subed-sort)
diff --git a/tests/test-subed-common.el b/tests/test-subed-common.el
index 266ebe692c..68154cc77f 100644
--- a/tests/test-subed-common.el
+++ b/tests/test-subed-common.el
@@ -3213,6 +3213,126 @@ This is another.
                   '("srt" "vtt" "ass")))
           function-list)))
 
+(describe "Setting subtitle"
+  (describe "text"
+    (it "replaces the text."
+      (with-temp-srt-buffer
+       (insert mock-srt-data)
+       (re-search-backward "Foo")
+       (subed-set-subtitle-text "Hello world")
+       (expect (subed-subtitle-text) :to-equal "Hello world")))
+    (it "replaces the text of a specified subtitle."
+      (with-temp-srt-buffer
+       (insert mock-srt-data)
+       (subed-set-subtitle-text "Hello world" 1)
+       (expect (subed-subtitle-text) :to-equal "Hello world")
+       (expect (subed-subtitle-id) :to-equal 1)))
+    (it "blanks out subtitles."
+      (with-temp-srt-buffer
+       (insert mock-srt-data)
+       (subed-set-subtitle-text "" 1)
+       (expect (subed-subtitle-text) :to-equal "")
+       (expect (subed-subtitle-id) :to-equal 1)
+       (expect (buffer-string) :to-equal
+               "1
+00:01:01,000 --> 00:01:05,123
+
+
+2
+00:02:02,234 --> 00:02:10,345
+Bar.
+
+3
+00:03:03,45 --> 00:03:15,5
+Baz.
+")))))
+
+(describe "Merging a region"
+  (it "handles empty buffers."
+    (with-temp-srt-buffer
+     (subed-merge-region (point-min) (point-max))
+     (expect (buffer-string) :to-equal "")))
+  (it "merges all the subtitles if requested."
+    (with-temp-srt-buffer
+     (insert mock-srt-data)
+     (expect (boundp 'subed--regenerate-ids-soon-timer) :to-be t)
+     (subed-merge-region (point-min) (point-max))
+     (expect (buffer-string) :to-equal "1
+00:01:01,000 --> 00:03:15,500
+Foo.
+Bar.
+Baz.
+")))
+  (it "merges some subtitles."
+    (with-temp-srt-buffer
+     (insert mock-srt-data)
+     (re-search-backward "Bar")
+     (subed-merge-region (point-min) (point))
+     (expect (buffer-string) :to-equal "1
+00:01:01,000 --> 00:02:10,345
+Foo.
+Bar.
+
+3
+00:03:03,45 --> 00:03:15,5
+Baz.
+")))
+  (it "merges some subtitles, including the last one."
+    (with-temp-srt-buffer
+     (insert mock-srt-data)
+     (re-search-backward "Bar")
+     (subed-merge-region (point) (point-max))
+     (expect (buffer-string) :to-equal "1
+00:01:01,000 --> 00:01:05,123
+Foo.
+
+2
+00:02:02,234 --> 00:03:15,500
+Bar.
+Baz.
+"))))
+
+(describe "Merging a region and setting the text"
+  (it "handles empty buffers."
+    (with-temp-srt-buffer
+     (subed-merge-region-and-set-text (point-min) (point-max) "")
+     (expect (buffer-string) :to-equal "")))
+  (it "merges all the subtitles if requested."
+    (with-temp-srt-buffer
+     (insert mock-srt-data)
+     (expect (boundp 'subed--regenerate-ids-soon-timer) :to-be t)
+     (subed-merge-region-and-set-text (point-min) (point-max) "Hello world")
+     (expect (buffer-string) :to-equal "1
+00:01:01,000 --> 00:03:15,500
+Hello world
+")))
+  (it "merges some subtitles."
+    (with-temp-srt-buffer
+     (insert mock-srt-data)
+     (re-search-backward "Bar")
+     (subed-merge-region-and-set-text (point-min) (point) "Hello world")
+     (expect (buffer-string) :to-equal "1
+00:01:01,000 --> 00:02:10,345
+Hello world
+
+3
+00:03:03,45 --> 00:03:15,5
+Baz.
+")))
+  (it "merges some subtitles, including the last one."
+    (with-temp-srt-buffer
+     (insert mock-srt-data)
+     (re-search-backward "Bar")
+     (subed-merge-region-and-set-text (point) (point-max) "Hello world")
+     (expect (buffer-string) :to-equal "1
+00:01:01,000 --> 00:01:05,123
+Foo.
+
+2
+00:02:02,234 --> 00:03:15,500
+Hello world
+"))))
+
 (describe "Conversion"
   (describe "from SRT"
     (describe "to VTT"