splash

README

splash

Build pre-paginated (fixed-layout) EPUB3 books from an ordered sequence of full-page images. A splash page is a page consisting of a single full-page image; every page this library emits is one — each input image becomes one page of the book, displayed full-bleed at its native dimensions.

• Deterministic — the same input and options always produce the same output bytes, so results can be golden-tested and content-addressed.
• Right-to-left aware — page-progression-direction and facing-page spread placement (page-spread-left/-right) come out correct for RTL books, with sensible automatic alternation.
• Zero non-stdlib dependencies.

See SPEC.md for the full specification.

go get github.com/ophymx/splash

Usage

book := splash.New("Uchuu no Hako").
    Language("ja").
    Direction(splash.RTL).
    Series("Uchuu no Hako", 1).
    Author("Aoyama Kawa")

if err := book.Cover(coverBytes); err != nil {
    return err
}
for _, data := range pages { // encoded JPEG/PNG/GIF, in reading order
    if err := book.AddPage(data, splash.PlacementAuto); err != nil {
        return err
    }
}
if err := book.WriteEPUB(out); err != nil {
    return err
}

Pages arrive as encoded bytes; format and pixel dimensions are sniffed (JPEG, PNG, GIF). Each page gets an XHTML content document with a matching viewport, so the reader scales it full-bleed. With PlacementAuto the first page is centered (a cover faces no partner) and the rest alternate into facing pairs by reading direction; pass an explicit PlacementLeft/ PlacementRight/PlacementCenter to re-anchor the alternation for books whose pagination starts mid-spread.

If no identifier is set, a stable urn:uuid is derived from the book's metadata and page bytes — same book in, same identifier out. dcterms:modified defaults to the Unix epoch, not the wall clock; set Modified(t) if you want a real timestamp.

Validation

go test validates generated files with epubcheck when it is available — an epubcheck binary on PATH, or EPUBCHECK=/path/to/epubcheck.jar with java installed — and skips the check otherwise. epubcheck is test-only tooling, never a runtime dependency.

KEPUB

Not yet: whether Kobo devices handle image-only fixed-layout books better as KEPUB or as plain EPUB3 is an open question to settle by device testing (see SPEC.md). If KEPUB wins, a WriteKEPUB built on pgaskin/kepubify will be added; if plain EPUB3 wins, it won't be.

Documentation

Overview

Package splash builds pre-paginated (fixed-layout) EPUB3 books from an ordered sequence of full-page images. A splash page is a page consisting of a single full-page image; every page this library emits is one. Each input image becomes one page of the book, displayed full-bleed at its native dimensions.

Output is deterministic: the same input and options always produce byte-identical files. See SPEC.md for the full specification.

Index

• type Book
  • func New(title string) *Book
  • func (b *Book) AddPage(data []byte, p Placement) error
  • func (b *Book) Author(name string) *Book
  • func (b *Book) Cover(data []byte) error
  • func (b *Book) Direction(d Direction) *Book
  • func (b *Book) Identifier(id string) *Book
  • func (b *Book) Language(tag string) *Book
  • func (b *Book) Modified(t time.Time) *Book
  • func (b *Book) Orientation(o Orientation) *Book
  • func (b *Book) Publisher(name string) *Book
  • func (b *Book) Series(name string, position float64) *Book
  • func (b *Book) Spread(s Spread) *Book
  • func (b *Book) WriteEPUB(w io.Writer) error
• type Direction
• type Orientation
• type Placement
• type Spread

Types

type Book

type Book struct {
	// contains filtered or unexported fields
}

Book accumulates metadata and pages, then writes them as an EPUB. Construct with New; metadata setters chain. Setter errors accumulate internally and surface at the write call; AddPage and Cover also return their error immediately.

func New

func New(title string) *Book

New returns a Book with the given title. Direction defaults to LTR, Spread to SpreadLandscape, Orientation to OrientationAuto.

func (*Book) AddPage

func (b *Book) AddPage(data []byte, p Placement) error

AddPage appends a page in reading order. data must be an encoded JPEG, PNG, or GIF image; format and pixel dimensions are sniffed from it.

func (*Book) Author

func (b *Book) Author(name string) *Book

Author adds an author. Call once per author; document order is preserved.

func (*Book) Cover

func (b *Book) Cover(data []byte) error

Cover appends a page flagged as the cover: its image carries the cover-image manifest property. If Cover is never called, the first page is the cover. At most one page may be the cover.

func (*Book) Direction

func (b *Book) Direction(d Direction) *Book

Direction sets the page progression direction.

func (*Book) Identifier

func (b *Book) Identifier(id string) *Book

Identifier sets the book's unique identifier (any URN/URI). When unset, an identifier is derived deterministically from the book's metadata and page bytes.

func (*Book) Language

func (b *Book) Language(tag string) *Book

Language sets the book's language as a BCP 47 tag (e.g. "en", "ja"). Required.

func (*Book) Modified

func (b *Book) Modified(t time.Time) *Book

Modified sets the publication's last-modified time (dcterms:modified). Defaults to the Unix epoch — a fixed value, not the wall clock, so output stays deterministic.

func (*Book) Orientation

func (b *Book) Orientation(o Orientation) *Book

Orientation sets the rendition:orientation hint.

func (*Book) Publisher

func (b *Book) Publisher(name string) *Book

Publisher sets the publisher.

func (*Book) Series

func (b *Book) Series(name string, position float64) *Book

Series records the series the book belongs to and its position in it. Position must be positive; fractions are allowed (2.5).

func (*Book) Spread

func (b *Book) Spread(s Spread) *Book

Spread sets the rendition:spread hint.

func (*Book) WriteEPUB

func (b *Book) WriteEPUB(w io.Writer) error

WriteEPUB validates the book and writes it to w as a fixed-layout EPUB3.

type Direction

type Direction int

Direction is the page progression direction of the book.

const (
	LTR Direction = iota // left-to-right (default)
	RTL                  // right-to-left
)

type Orientation

type Orientation int

Orientation is the rendition:orientation rendering hint.

const (
	OrientationAuto Orientation = iota // default
	OrientationLandscape
	OrientationPortrait
)

type Placement

type Placement int

Placement controls which side of a facing-page spread a page lands on, emitted as the page's spine spread property.

const (
	// PlacementAuto resolves at write time: the first page is centered (a
	// cover faces no partner), then pages alternate — RTL: right, left,
	// right, …; LTR: left, right, left, … — so consecutive pages land as
	// facing pairs. Explicit placements re-anchor the alternation.
	PlacementAuto Placement = iota
	PlacementLeft
	PlacementRight
	PlacementCenter
)

type Spread

type Spread int

Spread is the rendition:spread rendering hint: the device orientations in which the reader may lay out facing pages side by side.

const (
	SpreadLandscape Spread = iota // facing pages in landscape only (default)
	SpreadAuto
	SpreadBoth
	SpreadNone
)