nbk2pdf 1.0.0

data/lib/kindle_notebook/pdf_renderer.rb

@@ -0,0 +1,232 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Sergey Avseyev
+# frozen_string_literal: true
+
+require "prawn"
+
+module KindleNotebook
+  # Draws decoded pages as vector graphics. Canvas units are sub-pixels at the
+  # page's normalised PPI (2520 on a Scribe); PDF user space is points, and its
+  # Y axis points the other way, so every coordinate is scaled and flipped.
+  class PdfRenderer
+    HIGHLIGHTER_ALPHA = 0.2
+    MIN_LINE_WIDTH = 0.15
+
+    # Pages go on US Letter unless asked otherwise, since the size the device
+    # records matches no standard sheet and print dialogs then offer to scale.
+    DEFAULT_PAPER = "letter"
+
+    # Asking for this size keeps each page exactly as the device recorded it.
+    NATIVE_PAPER = "native"
+
+    # Resolves a paper name to [width, height] in points, or nil for the size
+    # the notebook itself records. No name at all means the default.
+    def self.paper(name = nil)
+      name = DEFAULT_PAPER if name.nil?
+      return nil if name.to_s.casecmp(NATIVE_PAPER).zero?
+
+      PDF::Core::PageGeometry::SIZES[name.to_s.upcase] ||
+        raise(Error, "unknown paper size #{name}; use #{NATIVE_PAPER} or one of " \
+                     "#{PDF::Core::PageGeometry::SIZES.keys.sort.join(", ")}")
+    end
+
+    # The pen reports a 12-bit pressure per point and the device narrows the
+    # line where the pen was lighter. The curve is not documented, so it was
+    # fitted against the thumbnails the device renders for the same pages; the
+    # fit says width follows how pressure varies *within* a stroke rather than
+    # its absolute level, since the stroke's overall width is already carried by
+    # nmdl.thickness. See "Stroke taper" in the README for the measurements.
+    PRESSURE_MAX = 4095
+    TAPER_SPAN = 1.15
+    MIN_WIDTH_FRACTION = 0.15
+
+    # Widths are rounded to this many steps so a stroke becomes a handful of
+    # sub-paths instead of one per sample point.
+    WIDTH_LEVELS = 8
+
+    # +paper+ is a resolved [width, height], or nil for the device's own size.
+    def initialize(render_template: true, paper: self.class.paper)
+      @render_template = render_template
+      @paper = paper
+    end
+
+    # +destination+ may be a path or any IO that responds to #write.
+    def render(pages, destination, title: nil)
+      raise Error, "notebook has no pages" if pages.empty?
+
+      document = new_document(pages.first, title)
+      pages.each_with_index do |page, index|
+        document.start_new_page(size: page_size(page), margin: 0) unless index.zero?
+        draw_page(document, page)
+      end
+      emit(document, destination)
+    end
+
+    # Draws one stroke in the page's own coordinates, points with the origin at
+    # the bottom left. +document+ is a Prawn document, or anything that answers
+    # the same few drawing calls.
+    def draw_stroke(document, page, stroke)
+      scale = POINTS_PER_INCH / page.ppi
+      nominal = [stroke.thickness * scale, MIN_LINE_WIDTH].max
+      points = stroke_points(page, stroke, scale)
+
+      document.stroke_color(rgb_hex(stroke.color))
+      document.fill_color(rgb_hex(stroke.color))
+
+      with_alpha(document, stroke_alpha(stroke)) do
+        if stroke.dot?
+          document.line_width(nominal)
+          document.fill_circle(points.first, nominal / 2)
+        else
+          draw_runs(document, points, segment_widths(stroke, nominal))
+        end
+      end
+    end
+
+    private
+
+    def new_document(first_page, title)
+      Prawn::Document.new(
+        page_size: page_size(first_page),
+        margin: 0,
+        info: {
+          Title: title,
+          Creator: "#{PROGRAM} #{VERSION}",
+          Producer: "#{PROGRAM} #{VERSION}"
+        }.compact
+      )
+    end
+
+    def emit(document, destination)
+      if destination.respond_to?(:write)
+        destination.write(document.render)
+      else
+        document.render_file(destination)
+      end
+      destination
+    end
+
+    def page_size(page) = @paper || [page.width_in_points, page.height_in_points]
+
+    def draw_page(document, page)
+      document.cap_style(:round)
+      document.join_style(:round)
+      fitted(document, page) do
+        draw_template(document, page) if @render_template
+        page.strokes.each { |stroke| draw_stroke(document, page, stroke) }
+      end
+    end
+
+    # On a chosen paper size the canvas is scaled to fit and centred, keeping
+    # its proportions, so nothing is stretched or cropped.
+    def fitted(document, page, &)
+      return yield if @paper.nil?
+
+      width = page.width_in_points
+      height = page.height_in_points
+      scale = [@paper.first / width, @paper.last / height].min
+      document.transformation_matrix(scale, 0, 0, scale,
+                                     (@paper.first - (width * scale)) / 2,
+                                     (@paper.last - (height * scale)) / 2, &)
+    end
+
+    def draw_template(document, page)
+      template = page.template
+      return if template.nil? || template.empty?
+      return if template.width <= 0 || template.height <= 0
+
+      # A template draws itself in its own space, which is stretched onto the page.
+      scale = [page.width_in_points / template.width, page.height_in_points / template.height]
+      template.shapes.each { |shape| draw_shape(document, page, shape, scale) }
+    end
+
+    def draw_shape(document, page, shape, scale)
+      alpha = alpha_of(shape.color)
+      return if alpha.zero?
+
+      scale_x, scale_y = scale
+      height = page.height_in_points
+      document.stroke_color(rgb_hex(shape.color))
+      document.line_width([shape.width * scale_x, MIN_LINE_WIDTH].max)
+      with_alpha(document, alpha) do
+        shape.segments.each do |segment|
+          polyline(document, segment.map { |x, y| [x * scale_x, height - (y * scale_y)] })
+        end
+      end
+    end
+
+    # One sub-path per run of equal width. Runs share their junction point, so
+    # with round caps and joins the seam between them is invisible.
+    def draw_runs(document, points, widths)
+      index = 0
+      while index < widths.size
+        width = widths[index]
+        last = index
+        last += 1 while last + 1 < widths.size && widths[last + 1] == width
+
+        document.line_width(width)
+        polyline(document, points[index..(last + 1)])
+        index = last + 1
+      end
+    end
+
+    # One width per segment, taken from the pressure at the segment's start and
+    # measured against the average pressure of the stroke it belongs to.
+    def segment_widths(stroke, nominal)
+      count = stroke.xs.size - 1
+      levels = taper_levels(stroke, count)
+      return Array.new(count, nominal) unless levels
+
+      mean = levels.sum / levels.size
+      levels.map { |level| width_for(level - mean, nominal) }
+    end
+
+    # The square root maps the raw reading onto something nearer to how wide the
+    # nib sits at that pressure.
+    #
+    # Only the pen tapers. The highlighter records pressure too, but it barely
+    # varies along a stroke while differing a lot between strokes, so following
+    # it would give each highlighter band an arbitrary thickness rather than the
+    # fixed one the device draws.
+    def taper_levels(stroke, count)
+      pressures = stroke.pressures
+      return nil if stroke.highlighter?
+      return nil unless pressures && pressures.size == stroke.xs.size
+
+      pressures.first(count).map { |p| Math.sqrt(p.clamp(0, PRESSURE_MAX) / PRESSURE_MAX.to_f) }
+    end
+
+    def width_for(offset, nominal)
+      factor = 1.0 + (TAPER_SPAN * offset)
+      factor = (factor * WIDTH_LEVELS).round / WIDTH_LEVELS.to_f
+      [nominal * factor, nominal * MIN_WIDTH_FRACTION, MIN_LINE_WIDTH].max
+    end
+
+    def stroke_points(page, stroke, scale)
+      height = page.height_in_points
+      stroke.xs.each_with_index.map { |x, index| [x * scale, height - (stroke.ys[index] * scale)] }
+    end
+
+    def stroke_alpha(stroke) = stroke.highlighter? ? HIGHLIGHTER_ALPHA : alpha_of(stroke.color)
+
+    def polyline(document, points)
+      document.move_to(points.first)
+      points.drop(1).each { |point| document.line_to(point) }
+      document.stroke
+    end
+
+    def with_alpha(document, alpha, &)
+      alpha < 1.0 ? document.transparent(alpha, &) : yield
+    end
+
+    # A colour is a packed integer; the alpha byte is only meaningful when the
+    # value actually carries one (templates do, pen colours do not).
+    def alpha_of(color)
+      return 1.0 if color <= 0xFF_FFFF
+
+      ((color >> 24) & 0xFF) / 255.0
+    end
+
+    def rgb_hex(color) = format("%06X", color & 0xFF_FFFF)
+  end
+end

data/lib/kindle_notebook/stroke_decoder.rb

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Sergey Avseyev
+# frozen_string_literal: true
+
+module KindleNotebook
+  # Every per-point array inside a stroke (x, y, pressure, tilt, ...) is stored
+  # as a second-order delta stream: the firmware records the change *of the
+  # change* between successive samples, which stays close to zero for a smooth
+  # pen movement and therefore packs into very few bits.
+  #
+  #   [0x01 0x01]        magic
+  #   [uint32-LE]        number of encoded values
+  #   [nibble stream]    one 4-bit instruction per value, two per byte
+  #   [operand bytes]    variable-width operands referenced by the nibbles
+  #
+  # Instruction nibble layout:
+  #
+  #   bits 0-1 (n)  operand width: 0 = none, 1..3 = that many little-endian bytes
+  #   bit 2         the increment is +n itself; no operand bytes are consumed
+  #   bit 3         negate the increment
+  module StrokeDecoder
+    MAGIC = "\x01\x01".b
+    HEADER_SIZE = 6
+
+    class DecodeError < Error; end
+
+    module_function
+
+    def decode(data, count)
+      return [] if count <= 0
+
+      data = data.to_s.b
+      raise DecodeError, "expected #{count} values in a #{data.bytesize}-byte blob" if data.bytesize < HEADER_SIZE
+      unless data.byteslice(0, 2) == MAGIC
+        raise DecodeError, "bad stroke signature #{data.byteslice(0, 2).unpack1("H*")}"
+      end
+
+      instructions, operand_offset = read_instructions(data, count)
+      accumulate(data, instructions, operand_offset, count)
+    end
+
+    def read_instructions(data, count)
+      nibbles = []
+      offset = HEADER_SIZE
+      while nibbles.size < count && offset < data.bytesize
+        byte = data.getbyte(offset)
+        offset += 1
+        nibbles << (byte >> 4) << (byte & 0x0F)
+      end
+      nibbles.pop if nibbles.size > count
+      [nibbles, offset]
+    end
+
+    def accumulate(data, instructions, offset, count)
+      values = Array.new(count)
+      change = 0
+      value = 0
+
+      count.times do |index|
+        instruction = instructions[index] || 0
+        width = instruction & 0x03
+        increment, offset =
+          if instruction.anybits?(0x04)
+            [width, offset]
+          else
+            read_operand(data, offset, width)
+          end
+        increment = -increment if instruction.anybits?(0x08)
+
+        if index.zero?
+          change = 0
+          value = increment
+        else
+          change += increment
+          value += change
+        end
+        values[index] = value
+      end
+      values
+    end
+
+    def read_operand(data, offset, width)
+      return [0, offset] if width.zero?
+      raise DecodeError, "stroke stream truncated" if offset + width > data.bytesize
+
+      value = data.byteslice(offset, width).each_byte.with_index.sum { |b, i| b << (8 * i) }
+      [value, offset + width]
+    end
+  end
+end

data/lib/kindle_notebook/titles.rb

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Sergey Avseyev
+# frozen_string_literal: true
+
+require "json"
+
+module KindleNotebook
+  # The names you gave your notebooks on the device.
+  #
+  # A Kindle keeps them on its system partition, which it does not share over
+  # MTP, and they are not in the notebook files either, so they have to be
+  # supplied once by hand. Notebooks that still have no name can be appended to
+  # the file for filling in, which is what `sync` does.
+  class Titles
+    HEADER = "# Names for your Kindle notebooks, which the device does not share over MTP.\n" \
+             "# Fill in a name between the quotes and it will be used from then on."
+    private_constant :HEADER
+
+    attr_reader :path
+
+    def self.load(path)
+      return new if path.nil?
+      return new(path: path) unless File.file?(path)
+
+      new(path: path, names: parse(File.read(path), path))
+    end
+
+    def self.parse(text, path)
+      data = json?(path) ? JSON.parse(text) : yaml(text)
+      raise Error, "#{path}: a title map must be a mapping of uuid to name" unless data.is_a?(Hash)
+
+      data.transform_keys(&:to_s).transform_values(&:to_s)
+    end
+
+    def self.yaml(text)
+      require "yaml"
+      YAML.safe_load(text, permitted_classes: [], aliases: false) || {}
+    end
+
+    def self.json?(path) = File.extname(path).casecmp(".json").zero?
+
+    def initialize(path: nil, names: {})
+      @path = path
+      @names = names
+      @missing = {}
+    end
+
+    def [](key) = @names[key]
+
+    # True once a uuid appears in the file at all, even without a name yet, so
+    # it is not offered for filling in twice.
+    def known?(uuid) = @names.key?(uuid)
+
+    # Remembers a notebook that has no name, with a note to recognise it by.
+    def note_missing(uuid, note)
+      @missing[uuid] ||= note unless known?(uuid)
+    end
+
+    def missing = @missing.size
+
+    # Adds the remembered notebooks to the file, and returns how many.
+    def record_missing
+      return 0 if @path.nil? || @missing.empty?
+
+      self.class.json?(@path) ? write_json : append_yaml
+      count = @missing.size
+      @missing.each_key { |uuid| @names[uuid] = "" }
+      @missing.clear
+      count
+    end
+
+    private
+
+    def append_yaml
+      File.open(@path, "a") do |file|
+        file.puts(HEADER) unless File.size?(@path)
+        @missing.each do |uuid, note|
+          file.puts
+          file.puts("# #{note}")
+          file.puts(%(#{uuid}: ""))
+        end
+      end
+    end
+
+    def write_json
+      merged = @names.merge(@missing.transform_values { "" })
+      File.write(@path, "#{JSON.pretty_generate(merged)}\n")
+    end
+  end
+end

data/lib/kindle_notebook/version.rb

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Sergey Avseyev
+# frozen_string_literal: true
+
+module KindleNotebook
+  VERSION = "1.0.0"
+
+  # The name this library is published and invoked under.
+  PROGRAM = "nbk2pdf"
+end

data/lib/nbk2pdf.rb

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Sergey Avseyev
+# frozen_string_literal: true
+
+# Reads Kindle Scribe notebooks (`nbk` files) and renders them as vector PDFs.
+module KindleNotebook
+  class Error < StandardError; end
+end
+
+require "kindle_notebook/version"
+require "kindle_notebook/container"
+require "kindle_notebook/ion"
+require "kindle_notebook/stroke_decoder"
+require "kindle_notebook/krds"
+require "kindle_notebook/notebook"
+require "kindle_notebook/document"
+require "kindle_notebook/pdf_renderer"
+require "kindle_notebook/document_renderer"
+require "kindle_notebook/titles"
+require "kindle_notebook/device"
+require "kindle_notebook/converter"
+require "kindle_notebook/cli"

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: nbk2pdf
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sergey Avseyev
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: combine_pdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: prawn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  Reads the `nbk` files a Kindle Scribe writes and renders them as vector PDFs,
+  complete with the ruled or squared background the notes were written on,
+  and adds what was written on a PDF on the device to a copy of that PDF.
+
+  Includes a reader for the signature container the device wraps its SQLite
+  database in, a binary Amazon Ion parser, and a decoder for the second-order
+  delta encoding the firmware stores pen strokes in. Ships the `nbk2pdf`
+  command line tool.
+email:
+- sergey.avseyev@gmail.com
+executables:
+- nbk2pdf
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- COPYING
+- README.md
+- exe/nbk2pdf
+- lib/kindle_notebook/cli.rb
+- lib/kindle_notebook/container.rb
+- lib/kindle_notebook/converter.rb
+- lib/kindle_notebook/device.rb
+- lib/kindle_notebook/document.rb
+- lib/kindle_notebook/document_renderer.rb
+- lib/kindle_notebook/ion.rb
+- lib/kindle_notebook/krds.rb
+- lib/kindle_notebook/notebook.rb
+- lib/kindle_notebook/pdf_renderer.rb
+- lib/kindle_notebook/stroke_decoder.rb
+- lib/kindle_notebook/titles.rb
+- lib/kindle_notebook/version.rb
+- lib/nbk2pdf.rb
+licenses:
+- GPL-3.0-or-later
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.22
+specification_version: 4
+summary: Convert Kindle Scribe notebooks into vector PDFs
+test_files: []