titlekit 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1b36a1f0921cdaa8ccdc52e9947507e17fa15000
+  data.tar.gz: c9925463a03d50b1486625d83e5df62ee4ab010a
+SHA512:
+  metadata.gz: d4eb3bf019168c863b72ed5c3eb05567ec5233fcfe71ca570f561fd08ad0da569f1bac69317f2c227c373144a05468e2efca751db90846e729fd47deb9741e03
+  data.tar.gz: 166c7fccd1d8085dba1cdf4c6eb49685d2ce20bdbb606fd58082dcd4e0e59c8dbd91f88474bd111ab58d431af0e062c0a11cfa128ce085c6def53ead5651b505

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+.bundle
+.config
+.ruby-gemset
+.ruby-version
+.rvmrc
+.rspec
+.yardoc
+Gemfile.lock
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Simon Repp
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,335 @@
+# Titlekit [![Build Status](https://travis-ci.org/simonrepp/titlekit.png)](https://travis-ci.org/simonrepp/titlekit)
+
+Featureful Ruby 2 library for SRT / ASS / SSA subtitles
+
+*Titlekit supports SRT, ASS and SSA, file format conversion, transcoding, automatic encoding detection, creation of simultaneous/multi-language subtitles, and timecode corrections with simple, progressive and framerate-based approaches. All of this is packed into a natural, dead-simple (and also irb-friendly) API.*
+
+## Installation
+
+**Patch level 2.0.0-p195 is mandatory because it contains necessary bugfixes for the new keyword arguments.**
+
+Add the `titlekit` gem to your gemfile or install it yourself:
+
+     $ gem install titlekit
+     
+### Optional installation recommendation
+
+Titlekit uses [rchardet19](https://github.com/oleander/rchardet) to detect unknown encodings; There is another library for this task called [charlock_holmes](https://github.com/brianmario/charlock_holmes), which offers more robust detection algorithms, but is not included by default because it relies on external C libraries that can make its installation anywhere from semi-easy to impossible. If you want Titlekit to use *charlock_holmes*, install it yourself, and Titlekit will automatically use it over *rchardet19*!
+
+## Documentation
+
+### Basic example
+
+A small hello world of Titlekit: **Converting from .srt to .ssa format**
+
+```ruby
+  job = Titlekit::Job.new             # (1) Initialize
+  job.have { file('existing.srt') }   # (2) Specify what you have
+  job.want { file('converted.ssa') }  # (3) Specify what you want
+  job.run                             # (4) Make it happen
+```
+### Checking success
+
+The return value from `#run` will tell you if the job was a success. If it was not,
+you can access `#report` to get messages related to the direct failure cause and also on
+anything suspicious that might have happened before (e.g. Low confidence when detecting an
+unknown encoding)
+
+```ruby
+  if job.run
+    # hooray
+  else
+    puts job.report.join("\n")
+  end
+```
+
+### All features by example
+
+In all following examples I will omit `(1)` and `(4)` from the basic example, because they stay the same.  
+All the functionalities from all the following examples can be combined in any way you want.
+
+#### Transcoding
+
+```ruby
+  job.have do
+    file('input.srt')
+    encoding('ISO-8859-1')
+  end
+  
+  job.want do
+    file('output.srt')
+    encoding('UTF-8')
+  end
+```
+
+#### Converting
+
+```ruby
+  job.have { file('input.ass') }
+  job.want { file('output.srt') }
+```
+
+#### Simple timeshifting
+
+```ruby
+  job.have do
+    file('input.srt')
+    reference('first sentence spoken', subtitle: 0)
+  end
+  
+  job.want do
+    file('output.srt')
+    reference('first sentence spoken', srt_timecode: '00:00:54,200')
+  end
+```
+
+#### Progressive timeshifting
+
+```ruby
+  job.have do
+    file('input.srt')
+    reference('first subtitle', subtitle: 0)
+    reference('last subtitle', subtitle: 475)
+  end
+  
+  job.want do
+    file('output.srt')
+    reference('first subtitle', minutes: 3.76)
+    reference('last subtitle', hours: 1.8912)
+  end
+```
+
+#### Framerate-based timeshifting
+
+```ruby
+  job.have do
+    file('input.srt')
+    fps(25)
+  end
+  
+  job.want do
+    file('output.srt')
+    fps(23.976)
+  end
+```
+
+#### Mixed mode timeshifting
+
+```ruby
+  job.have do
+    file('input.srt')
+    fps(25)
+    reference(:first_sub, subtitle: 0)
+  end
+  
+  job.want do
+    file('output.srt')
+    fps(23.976)
+    reference(:first_sub, minute: 13.49)    
+  end
+```
+
+#### Merging
+
+Subtitles that don't overlap are automatically merged and treated as one track.
+
+```ruby
+  job.have do
+    file('subs_chapter1.srt')
+  end
+
+  job.have do
+    file('subs_chapter2.srt')
+  end
+
+  job.want do
+    file('subs_both_chapters_combined.srt')
+  end
+```
+
+#### Merging (with time correction)
+
+If each of your individual subtitle files contains timecodes relative to its own starting point,
+you have to supply a reference so misaligned subtitles can be automatically shifted. When you fail
+to do this, your subtitles overlap and thus Titlekit assumes that you want simultaneous subtitles (which are explained in the next paragraph below this one).
+
+```ruby
+  job.have do
+    file('subs_cd1.srt')
+  end
+
+  job.have do
+    file('subs_cd2.srt')
+    reference(:cd2_subtitles_starting_at, minutes: 0)
+  end
+
+  job.want do
+    reference(:cd2_subtitles_starting_at, srt_timecode: '00:01:24,000')
+    file('subs_both_cds_combined.srt')
+  end
+```
+
+#### Simultaneous/multi-lanugage subtitles
+
+Subtitles that overlap are automatically treated as simultaneous/multi-lanugage subtitles.
+Titlekit then positions and formats them in the most sensible way it sees fit.
+
+```ruby
+  job.have { file('enlish.srt') }
+  job.have { file('dutch.srt') }
+  job.want { file('dual-language.srt') }
+```
+
+Any target format is possible, Titlekit will automatically make the best use of the formatting
+features your target format provides. Pick a sophisticated subtitle format, and your dual
+subtitles will automatically be prettier and more readable!
+
+```ruby
+  job.have { file('enlish.srt') }
+  job.have { file('dutch.srt') }
+  job.want { file('dual-language-prettier.ass') }
+```
+
+You can also go crazy if you want, Titlekit can handle it.
+
+```ruby
+  job.have { file('enlish.srt') }
+  job.have { file('dutch.srt') }
+  job.have { file('spanish.srt') }
+  job.have { file('german.srt') }
+  job.have { file('italian.srt') }
+  job.have { file('french.srt') }
+  job.have { file('portuguese.srt') }
+  job.have { file('russian.srt') }
+  job.want { file('messy-but-supported.ssa') }
+```
+
+#### Mixed mode Merging (implicit)
+
+If you really need the absurdly exotic case of merging multi-part subtitles into multiple simultaneous tracks, you just need to make sure you enter them in the correct order, which is: Lanuage1/Part1 -> Language1/Part2 -> Language2/Part1 -> Language2/Part2
+
+```ruby
+  job.have { file('subs_english_chapter1.srt')
+  job.have { file('subs_english_chapter2.srt')
+  job.have { file('subs_french_chapter1.srt')
+  job.have { file('subs_french_chapter2.srt')
+
+  job.want do
+    file('subs_multi_part_multi_track.srt')
+  end
+```
+
+#### Mixed mode Merging (explicit)
+
+If you supply explicit track identifiers by which to material should be grouped into tracks, 
+you can also forget all about the otherwise required order and just go wild:
+
+```ruby
+
+  job.have do
+    file('subs_french_chapter2.srt')
+    track('le-french-track')
+  end
+
+  job.have do
+    file('subs_english_chapter1.srt')
+    track('the-english-one')
+  end
+
+  job.have do
+    file('subs_french_chapter1.srt')
+    track('le-french-track')
+  end
+
+  job.have do
+    file('subs_english_chapter2.srt')
+    track('the-english-one')
+  end
+
+  job.want do
+    file('subs_multi_part_multi_track.srt')
+  end
+```
+
+#### Multiple targets
+
+```ruby
+  job.have { file('input.srt') }
+  job.want { file('output.ass') }
+  job.want { file('output.ssa') }
+```
+
+#### Templates
+
+```ruby
+  job.have do
+    file('input.srt')
+    encoding('Shift_JIS')
+    reference(:some_subtitle, subtitle: 23)
+  end
+  
+  templ = job.want do
+    file('output.srt')
+    encoding('UTF-8')
+    reference(:some_subtitle, hours: 0.16)
+  end
+  
+  job.want(template: templ) { file('output.ass') }
+  job.want(template: templ) { file('output.ssa') }
+```
+
+#### Explicitly control encoding detection
+
+```ruby
+  job.have do
+    file('input.srt')
+    encoding(:detect) # Detect the encoding with charlock_holmes if installed, otherwise rchardet19
+                      # You don't need to supply this line though, it's the default behavior!
+  end
+
+  job.have do
+    file('input.srt')
+    encoding(:rchardet19) # Explicitly use rchardet19
+  end  
+  
+  job.have do
+    file('input.srt')
+    encoding(:charlock_holmes) # Explicitly use charlock_holmes
+  end
+```
+
+#### Syntax Variants
+
+`#have` and `#want` offer three different syntax variants, which are functionally identical:
+
+```ruby
+  job.have do
+    file('input.srt')
+    encoding('ISO-8859-1')
+  end
+  
+  # is identical to
+  
+  job.have do |have|
+    have.file('input.srt')
+    have.encoding('ISO-8859-1')
+  end
+  
+  # is identical to
+  
+  have = job.have
+  have.file('input.srt')
+  have.encoding('ISO-8859-1')
+```
+
+## API Reference
+
+http://www.rubydoc.info/gems/titlekit/frames (or generate it yourself with YARD)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec

data/lib/titlekit/have.rb

@@ -0,0 +1,90 @@
+module Titlekit
+
+  # Specifies existing input for a job.
+  class Have < Specification
+
+    def initialize
+      super
+
+      @encoding = :detect
+    end
+
+    # @param [String, Symbol] A string specifying the encoding if it is known,
+    #   (e.g. 'UTF-8', 'ISO-8859-1'), :detect in case you don't know, and
+    #   :rchardet19 or :charlock_holmes if you have installed an additional
+    #   detection library and want to specifically use one or the other.
+    #
+    # @return If you omit the argument, it returns the already specified encoding
+    def encoding(*args)
+      if args.empty?
+        return @encoding
+      else
+        @encoding = args[0]
+        return self
+      end
+    end
+
+    # Places a named reference (in the form of a string or a symbol) on
+    # either a +subtitle+ index or a timecode specified by either
+    # +hours+, +minutes+, +seconds+ or +milliseconds+.
+    #
+    # Its typical use-case is to reference a specific subtitle you can
+    # recognize in both the movie and your subtitle file, where usually
+    # for the subtitle file (represented by {Have}) you will reference
+    # the subtitle index and for the movie (represented by {Want}) you
+    # will reference the timecode that is displayed when the line occurs
+    # in the movie.
+    #
+    # @example Referencing a subtitle index (ZERO-INDEXED! First subtitle is 0)
+    #   have.reference('Earl grey, hot', subtitle: 645)
+    #  
+    # @example Referencing a timecode by seconds
+    #   have.reference('In a galaxy ...', seconds: 14.2)
+    #
+    # @example Referencing a timecode by an SRT-style timecode
+    #   have.reference('In a galaxy ...', srt_timecode: '00:00:14,200')
+    #
+    # @example Referencing a timecode by an ASS-style timecode
+    #   have.reference('In a galaxy ...', ass_timecode: '0:00:14,20')
+    #
+    # @example Referencing a timecode by an SSA-style timecode
+    #   have.reference('In a galaxy ...', ssa_timecode: '0:00:14,20')
+    #
+    # @example Symbols can be used as references as well!
+    #   have.reference(:narrator_begins, minutes: 7.9)
+    #
+    # @param name [String, Symbol] The name of the reference
+    # @param subtitle [Integer] Heads up: Numbering starts at 1!
+    # @param hours [Float]
+    # @param minutes [Float]
+    # @param seconds [Float]
+    # @param milliseconds [Float]
+    def reference(name,
+                  *args,
+                  subtitle: nil,
+                  hours: nil,
+                  minutes: nil,
+                  seconds: nil,
+                  milliseconds: nil,
+                  srt_timecode: nil,
+                  ssa_timecode: nil,
+                  ass_timecode: nil)
+
+      if subtitle
+        @references[name] = { subtitle: subtitle }
+      else
+        super(name,
+              hours: hours,
+              minutes: minutes,
+              seconds: seconds,
+              milliseconds: milliseconds,
+              srt_timecode: srt_timecode,
+              ssa_timecode: ssa_timecode,
+              ass_timecode: ass_timecode)
+      end
+
+      return self
+    end
+  end
+  
+end