EpubFs 0.5.1
dotnet add package EpubFs --version 0.5.1
NuGet\Install-Package EpubFs -Version 0.5.1
<PackageReference Include="EpubFs" Version="0.5.1" />
<PackageVersion Include="EpubFs" Version="0.5.1" />
<PackageReference Include="EpubFs" />
paket add EpubFs --version 0.5.1
#r "nuget: EpubFs, 0.5.1"
#:package EpubFs@0.5.1
#addin nuget:?package=EpubFs&version=0.5.1
#tool nuget:?package=EpubFs&version=0.5.1
EpubFs
EPUB authoring library for F#.
Nuget package
Project status
This library has been extracted from a personal project of mine and represents the bare minimum necessary to create EPUB files for my purposes. As such, I do not intend to continue developing any new major features.
However, if you or your company have a need for a particular feature or require that some other part of the EPUB spec be implemented, and you are willing to pay for the development, I would be more than happy to work with you!
Bug reports and PRs will naturally still be looked at.
Usage
In order to create an EPUB, you need to supply some metadata and a file manifest including the title page, list of files with the actual book content as well as any CSS files you want to use.
Content files
Content files are accepted in the form of XmlNode list, which you can construct using the Giraffe.ViewEngine DSL, or as a Stream containing an XHTML that you have obtained in some other way.
CSS files
You can also include stylesheets to be used in the book. If a content file is provided as XmlNode list, every CSS file will automatically be referenced therein. On the other hand, if you're supplying a full XHTML file, you need to import the stylesheet (in the traditional HTML fashion) yourself by using the FileName of a matching CSS file.
Table of contents (navigation document)
Every EPUB requires a navigation document. There are two choices here - either you supply an XHTML (it has to conform to the navigation spec!) directly, or you let the library generate a simple table of contents page with hyperlinks to each of your content files (whose Navigation is not set to None).
The generated document's headings and fixed entries come from NavLabels - pass Autogenerated NavLabels.English or your own translations.
It also contains a hidden list of landmarks, which reading systems use for "go to" menus: the table of contents, the start of the content (the first file with Navigation set), and every file (title page included) whose Landmark is set to a structural semantics type, such as titlepage, glossary or appendix, labelled with the file's Title.
Page progression direction
Set the manifest's PageProgressionDirection to Some Rtl for books whose pages turn right to left (Arabic, Hebrew, vertical Japanese...). None leaves it up to the reading system.
Media overlays (SMIL)
Starting from v0.4 the library supports EPUB Media Overlays, which allow you to synchronize audio narration with text content using SMIL files.
To add media overlays:
- Include your audio files in the manifest's
OtherFileslist - For each content file that should have audio synchronization, set the
Smilproperty with aSmilFilerecord - Add
MediaOverlaymetadata to yourMetadatarecord, including the total duration
SMIL content can be provided in three ways:
SmilInput.Raw- A pre-built SMIL file as a streamSmilInput.Structured- A list ofXmlNoderepresenting the SMIL head and body contentSmilInput.ParNodes- A simplified list ofParNoderecords, where each generates a<par>element with text and audio synchronization
For the sake of simplicity, the API assumes that every SMIL file references exactly one audio file (but many SMIL files can reference the same audio file) despite the fact that the spec allows references to multiple audio files.
Additional metadata and prefixes
Starting from v0.5 you can add arbitrary <meta> elements to the package metadata via Meta, for properties the Metadata record doesn't model directly, such as rendition:flow or reading-system-specific ones. Each MetaProperty can optionally refine another element by ID via Refines (e.g. "#creator1" for the first creator).
Properties from vocabularies outside the reserved prefixes (dcterms, rendition, a11y, ...) need their prefix declared in Prefixes. The media prefix is always declared.
For example, Apple Books only uses embedded fonts by default if the book says so:
Prefixes = [ { Name = "ibooks"; Iri = "http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/" } ]
Meta = [ { Property = "ibooks:specified-fonts"; Value = "true"; Refines = None } ]
Example
open EpubFs
open Giraffe.ViewEngine
open System.IO
open System.Text
let metadata = {
// A unique book identifier, could be ISBN or URL...
Id = "my-book"
Title = "Ὀδύσσεια"
// List of language tags - you should use ISO 639-2
// If you specify more than one, the first is considered the primary language of the book
Languages = [ "grc" ]
// `None` defaults to DateTimeOffset.UtcNow
ModifiedAt = None
Source = Some "https://el.wikisource.org/wiki/%CE%9F%CE%B4%CF%8D%CF%83%CF%83%CE%B5%CE%B9%CE%B1"
Creators = [ "John Doe"; "Ὅμηρος" ]
Description = Some "The epic tale of Odysseus's journey home."
Publisher = Some "Ancient Greek Press"
Subjects = [ "Epic Poetry"; "Greek Literature"; "Mythology" ]
Rights = Some "Public Domain"
// Media overlay metadata - required when using SMIL
MediaOverlay = Some {
TotalDuration = Choice2Of2 (TimeSpan.FromSeconds 5.0)
ActiveClass = Some "-epub-media-overlay-active"
PlaybackActiveClass = None
Narrators = [ "Narrator Name" ]
}
// Vocabulary prefixes for non-reserved properties used in `Meta`
Prefixes = []
// Additional <meta> elements
Meta = [ { Property = "rendition:flow"; Value = "paginated"; Refines = None } ]
}
// The CSS Stream you would like to use throughout the book
let css = new MemoryStream (".red-font { color: red }"B)
// Audio file for narration
use audioStream = File.OpenRead "chapter1.mp3"
// Let's declare the title page document using `Giraffe.ViewEngine`
// Use the `red-font` class from our stylesheet
let titlePage = {
FileName = "title.xhtml"
Title = "Title"
Input = Structured [
h1 [ _class "red-font" ] [
str "Ὀδύσσεια"
]
]
Navigation = None
Smil = None
// Listed in the landmarks of the generated navigation document
Landmark = Some "titlepage"
}
// We already have a pre-built XHTML of the first content document, so pass it as a stream
// Notice the manual reference to our stylesheet
use chapter1Stream =
"""<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head><link href="main.css" type="text/css" rel="stylesheet"/><title>Page one</title></head><body><div id="line1" class="red-font">Ἄνδρα μοι ἔννεπε, Μοῦσα, πολύτροπον, ὃς μάλα πολλὰ</div><div id="line2">πλάγχθη, ἐπεὶ Τροίης ἱερὸν πτολίεθρον ἔπερσε·</div></body></html>"""
|> Encoding.UTF8.GetBytes
|> MemoryStream
let chapter1 = {
FileName = "chapter1.xhtml"
Title = "Chapter 1"
Input = ContentInput.Raw chapter1Stream
// Setting navigation to `Some` so that this document appears in the table of contents
Navigation = Some Linear
Landmark = None
// Associate a SMIL file for audio synchronization
// Notice references to div IDs of the chapter file above, and audio references to the file added in the manifest below
Smil = Some {
Duration = Choice2Of2 (TimeSpan.FromSeconds 5.0)
Input = SmilInput.ParNodes ("chapter1.mp3", [
{
TextFragmentReference = "#line1"
ClipBegin = Choice2Of2 TimeSpan.Zero
ClipEnd = Choice2Of2 (TimeSpan.FromSeconds 2.5)
}
{
TextFragmentReference = "#line2"
ClipBegin = Choice1Of2 "00:00:02.500"
ClipEnd = Choice2Of2 (TimeSpan.FromSeconds 5.0)
}
])
}
}
let manifest = {
// Usually used by e-book readers as the book thumbnail
CoverImage = None
// Table of contents will be generated for us, with English headings
NavigationFile = Autogenerated NavLabels.English
TitlePage = titlePage
ContentFiles = [ chapter1 ]
CssFiles = [
// The file will be stored in the archive under this name
// It's also what you use to reference the stylesheet in XHTML
{ FileName = "main.css"; Input = css }
]
OtherFiles = [
{ FileName = "chapter1.mp3"; MediaType = "audio/mpeg"; Input = audioStream; Compress = false }
]
// Left to the reading system
PageProgressionDirection = None
}
use fs = File.OpenWrite "odyssey.epub"
do! Write.write fs metadata manifest
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- FSharp.Core (>= 6.0.5)
- Giraffe.ViewEngine (>= 1.4.0 && < 3.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.