Untertitel zu Videos in Ruby mit Open-Source-Tools hinzufügen

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Untertitel in Videos verbessern Barrierefreiheit, Zuschauerbindung und SEO erheblich. Ruby-Entwickler haben Zugriff auf mehrere leistungsstarke Open-Source-Tools, die das Einbinden und Bearbeiten von Untertiteln vereinfachen. Sehen wir uns an, wie Sie diese Tools wirkungsvoll einsetzen.

Warum Untertitel wichtig sind

Untertitel nützen nicht nur Zuschauerinnen und Zuschauern mit Hörbehinderung – sie verbessern auch das Verständnis für Personen, die die Sprache nicht als Muttersprache sprechen, stärken SEO, weil Inhalte durchsuchbar werden, und können die Zuschauerbindung erhöhen. Untertitel anzubieten wird zunehmend zum Standard für inklusive und barrierefreie Inhalte.

Open-Source-Tools in Ruby für Untertitel

Ruby bietet mehrere robuste Bibliotheken für die Verwaltung von Untertiteln, die in erster Linie das leistungsstarke Multimedia-Framework FFmpeg ansprechen oder Untertiteldateien direkt bearbeiten:

streamio-ffmpeg: Ein umfassender Ruby-Wrapper für FFmpeg, der verschiedene Aufgaben der Videoverarbeitung ermöglicht, darunter das Einbrennen von Untertiteln in Videos oder das Konvertieren von Untertitelformaten.
srt: Ein spezialisiertes Gem zum Parsen, Bearbeiten und Erzeugen von SRT-Untertiteldateien (SubRip Text), dem gängigsten Untertitelformat.

Sehen wir uns praktische Beispiele mit diesen Tools an.

Untertitel mit streamio-ffmpeg hinzufügen

Das Gem streamio-ffmpeg bietet eine komfortable Ruby-Schnittstelle zu FFmpeg und macht es einfach, Untertitel in Videos einzubetten. Dieser Vorgang wird oft als „Einbrennen“ von Untertiteln bezeichnet, was bedeutet, dass sie Teil der Videobilder werden.

Verwenden Sie eine gepflegte Ruby-Version und einen FFmpeg-Build mit dem Filter subtitles von libass, dem Encoder libx264 sowie FFprobe. Prüfen Sie den Filter mit ffmpeg -filters; er ist nicht in jedem Paket-Build enthalten. Installieren Sie diese getesteten Gem-Versionen:

gem install streamio-ffmpeg:3.0.2 srt:0.1.5

Speichern Sie diese gemeinsame Implementierung als subtitle_tools.rb. Alle folgenden Beispiele greifen darauf zurück. Das temporäre Verzeichnis hält den Dateinamen der Untertitel aus der Filtersyntax von FFmpeg heraus und schirmt das Überschreibverhalten des Wrappers von vorhandenen Ausgaben ab. Für die Veröffentlichung wird ein Hardlink im Ausgabedateisystem verwendet; das Dateisystem muss Hardlinks unterstützen.

require 'streamio-ffmpeg'
require 'srt'
require 'tmpdir'

module SubtitleTools
  def self.load_srt(path)
    raise ArgumentError, 'Subtitle input must be a regular file' unless File.file?(path)
    text = File.binread(path, 1024 * 1024 + 1)
    raise ArgumentError, 'Subtitle input exceeds 1 MiB' if text.bytesize > 1024 * 1024
    text.force_encoding(Encoding::UTF_8)
    raise ArgumentError, 'Subtitles must be valid UTF-8' unless text.valid_encoding?
    subtitles = SRT::File.parse(text)
    if subtitles.lines.empty? || !subtitles.errors.empty?
      raise ArgumentError, 'Invalid or empty SRT input'
    end
    unless subtitles.lines.all? { |line| line.start_time >= 0 && line.end_time > line.start_time }
      raise ArgumentError, 'Invalid subtitle timing'
    end
    subtitles
  end

  def self.with_output(output_path, extension)
    output = File.expand_path(output_path)
    if File.exist?(output) || File.symlink?(output)
      raise ArgumentError, 'Output must not exist'
    end
    Dir.mktmpdir('.subtitles-', File.dirname(output)) do |temporary|
      candidate = File.join(temporary, "result#{extension}")
      yield candidate, temporary
      raise IOError, 'No nonempty output produced' unless File.file?(candidate) && File.size(candidate) > 0
      File.link(candidate, output)
    end
  end

  def self.burn(video_path, subtitle_path, output_path)
    subtitles = load_srt(subtitle_path)
    movie = FFMPEG::Movie.new(File.expand_path(video_path))
    raise ArgumentError, 'Invalid video input' unless movie.valid?
    with_output(output_path, '.mp4') do |_candidate, temporary|
      File.write(File.join(temporary, 'captions.srt'), subtitles.to_s)
      # Fixed basenames avoid FFmpeg's separate filter-path escaping rules.
      Dir.chdir(temporary) do
        movie.transcode('result.mp4', {
          video_codec: 'libx264', audio_codec: 'aac',
          custom: ['-nostdin', '-vf', 'subtitles=captions.srt', '-threads', '2']
        })
      end
    end
  end

  def self.write_srt(subtitles, output_path)
    with_output(output_path, '.srt') { |candidate| File.write(candidate, subtitles.to_s) }
  end

  def self.convert_to_vtt(subtitle_path, output_path)
    subtitles = load_srt(subtitle_path)
    with_output(output_path, '.vtt') do |candidate, temporary|
      input = File.join(temporary, 'captions.srt')
      File.write(input, subtitles.to_s)
      unless system('ffmpeg', '-nostdin', '-n', '-i', input, '-c:s', 'webvtt', candidate)
        raise IOError, 'Subtitle conversion failed'
      end
    end
  end
end

Diese Implementierung ist für einen sequenziellen CLI-Worker gedacht: Dir.chdir wirkt sich auf den gesamten Ruby-Prozess aus, rufen Sie diese Methode daher nicht gleichzeitig aus mehreren Threads auf. Verwenden Sie beim Skalieren separate, isolierte Prozesse. FFmpeg und der Parser müssen bei nicht vertrauenswürdigen Dateien dennoch mit Ressourcenlimits laufen; sichere Dateinamen ersetzen keine Sandbox für die Medienverarbeitung. Der Helper codiert Video und Audio neu in MP4.

Verwenden Sie die Implementierung aus einem Skript im selben Verzeichnis:

require_relative 'subtitle_tools'

SubtitleTools.burn('input.mp4', 'subtitles.srt', 'output_with_subs.mp4')
puts 'Subtitles added'

SRT-Dateien mit dem SRT-Gem bearbeiten

Mit dem Gem srt können Sie SRT-Untertiteldateien programmgesteuert parsen, ändern und erstellen. Das ist nützlich für Aufgaben wie das Anpassen von Timings, das Korrigieren von Text oder das Erzeugen von Untertiteln von Grund auf.

require_relative 'subtitle_tools'

subtitles = SubtitleTools.load_srt('subtitles.srt')
subtitles.timeshift(all: '+2.5s')
SubtitleTools.write_srt(subtitles, 'modified.srt')
puts 'Subtitles shifted by 2.5 seconds'

Die Methode timeshift des Gems erwartet einen Options-Hash und keine numerische Verzögerung. Der Parser kann Fehler an den Untertitelzeilen vermerken, statt eine eigene Ausnahme vom Typ SRT::Error auszulösen; der gemeinsame Loader prüft diese gemeldeten Fehler und validiert positive Cue-Dauern vor der Verarbeitung.

Untertitelformate konvertieren

Während sich das Gem srt speziell auf das SRT-Format konzentriert, können Sie FFmpeg mithilfe des Gems streamio-ffmpeg nutzen, um zwischen verschiedenen Untertitelformaten zu konvertieren. Das ist besonders nützlich für webbasierte Videoplayer, die häufig das WebVTT-Format bevorzugen.

require_relative 'subtitle_tools'

SubtitleTools.convert_to_vtt('subtitles.srt', 'subtitles.vtt')
puts 'WebVTT subtitles saved'

Der Helper führt FFmpeg mit getrennten Argumenten aus, prüft dessen Exit-Status und veröffentlicht nur ein nicht leeres Ergebnis. Halten Sie die Wahl von Format und Dateiendung zusammen, wenn Sie ihn an einen anderen Codec anpassen.

Fehlerbehandlung bei der Untertitel-Integration

Lassen Sie Fehler der Helper bis zu einer einzigen CLI-Grenze durchschlagen. Speichern Sie dies als add_subtitles.rb neben subtitle_tools.rb; es gibt einen Status ungleich null zurück, ohne rohe Decoder- oder Dokumentfehler offenzulegen.

require_relative 'subtitle_tools'

abort 'Usage: ruby add_subtitles.rb <video.mp4> <subtitles.srt> <new-output.mp4>' unless ARGV.length == 3
begin
  SubtitleTools.burn(*ARGV)
  puts 'Subtitles added'
rescue StandardError
  warn 'Subtitle processing failed. Check the inputs, output path, and FFmpeg installation.'
  exit 1
end

Führen Sie ruby add_subtitles.rb input.mp4 subtitles.srt output_with_subs.mp4 aus. Decoder-Diagnosen können weiterhin in einem lokalen FFmpeg-Log erscheinen; senden Sie diese Logs nicht direkt an Web-Clients.

Unterstützte Untertitelformate

Bei der Arbeit mit Untertiteln, insbesondere mit FFmpeg, begegnen Ihnen verschiedene Formate. Zu den wichtigsten Formaten gehören:

SRT (SubRip Text): .srt - Das am weitesten verbreitete Klartextformat. Es wird direkt vom Gem srt und von FFmpeg unterstützt.
WebVTT (Web Video Text Tracks): .vtt - Der Standard für Untertitel in HTML5-Videos, der Styling und Positionierung unterstützt. FFmpeg kann in dieses Format und aus diesem Format konvertieren.
ASS/SSA (Advanced SubStation Alpha / SubStation Alpha): .ass / .ssa - Fortgeschrittenere Formate, die komplexes Styling, Positionierung und Effekte unterstützen und häufig in Anime-Fansubs verwendet werden. FFmpeg unterstützt sie gut.
SBV (SubViewer): .sbv - Ein einfaches Format, das YouTube verwendet. FFmpeg beherrscht die Konvertierung.

FFmpeg unterstützt die Konvertierung zwischen diesen und weiteren Formaten umfassend. Das Gem srt konzentriert sich speziell auf das Parsen und Bearbeiten des SRT-Formats.

Praxisbeispiel: Videos mit Untertiteln im Batch verarbeiten

Das folgende Skript zeigt, wie Sie mehrere Videos in einem Verzeichnis verarbeiten und dabei passende SRT-Untertitel hinzufügen, sofern sie gefunden werden.

require_relative 'subtitle_tools'

def batch_process_videos(video_dir, subtitle_dir, output_dir)
  video_files = Dir.children(video_dir).sort.filter_map do |name|
    path = File.join(video_dir, name)
    path if File.extname(name).downcase == '.mp4' && File.file?(path) && !File.symlink?(path)
  end
  raise ArgumentError, 'No MP4 files found' if video_files.empty?
  Dir.mkdir(output_dir, 0700)
  failures = 0
  video_files.each do |video|
    basename = File.basename(video, File.extname(video))
    begin
      SubtitleTools.burn(video, File.join(subtitle_dir, "#{basename}.srt"),
                         File.join(output_dir, "#{basename}_subtitled.mp4"))
      puts "Converted #{basename}"
    rescue StandardError
      failures += 1
      warn "Conversion failed for #{basename}"
    end
  end
  failures.zero? ? 0 : 1
end

abort 'Usage: ruby batch_subtitles.rb <videos> <subtitles> <new-output-directory>' unless ARGV.length == 3
begin
  exit batch_process_videos(*ARGV)
rescue StandardError
  warn 'Cannot prepare batch. Check input directories and use a new output directory.'
  exit 1
end

Das Skript durchläuft die MP4-Dateien in einem angegebenen Verzeichnis, sucht in einem anderen Verzeichnis nach einer passenden SRT-Datei und verarbeitet jedes Paar mit SubtitleTools.burn, wobei die Ausgabe in einem dafür vorgesehenen Ordner landet. Speichern Sie es als batch_subtitles.rb. Fehlende oder ungültige Untertitel gelten als Fehlschlag, die übrigen Dateien werden aber dennoch verarbeitet. Fertige Ausgaben bleiben erhalten, und unvollständige temporäre Dateien werden aufgeräumt. Der Gesamt-Exit-Status meldet, ob alle Konvertierungen erfolgreich waren.

Fazit

Untertitel lassen sich mit Ruby unkompliziert zu Videos hinzufügen, wenn Sie Open-Source-Tools wie streamio-ffmpeg (als Schnittstelle zu FFmpeg) und das Gem srt einsetzen. Diese Bibliotheken vereinfachen das Einbrennen von Untertiteln in Videos, das Bearbeiten von SRT-Dateien und das Konvertieren zwischen Formaten und verbessern so die Barrierefreiheit und die Zuschauerbindung Ihres Videos deutlich. Denken Sie daran, mögliche Fehler sauber abzufangen, damit Ihre Anwendungen robust bleiben.

Für komplexere Untertitel-Workflows, Videoverarbeitung in großem Maßstab oder cloudbasierte Lösungen sollten Sie einen spezialisierten Dienst in Betracht ziehen. Transloadits Robot 🤖 /video/subtitle bietet fortgeschrittene Funktionen zur Untertitel-Integration als Teil des Video-Encoding-Service und verarbeitet verschiedene Formate und Stile effizient.