Readium Swift Toolkit

https://readium.org/swift-toolkit
Admin
Readium Swift Toolkit is a toolkit for developing reading apps on iOS and iPadOS with support for...
Tokens:512,451
Snippets:4,886
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### start(with:isPlaying:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/audiosession/start%28with%3Aisplaying%3A%29

Starts a new audio session with the given user and playback state.

```APIDOC
## start(with:isPlaying:)

### Description
Starts a new audio session with the given `user`.

### Method
Instance Method

### Signature
```swift
nonisolated
func start(
    with user: AudioSessionUser,
    isPlaying: Bool
)
```

### Parameters
- **user** (AudioSessionUser) - The user for whom the audio session is started.
- **isPlaying** (Bool) - Indicates whether audio is currently playing.

### Return Value
None (void).
```

--------------------------------

### init(guided: [GuidedNavigationObject])

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/guidednavigationdocument

Initializes a GuidedNavigationDocument with a sequence of guided navigation objects.

```APIDOC
## init(guided: [GuidedNavigationObject])

### Description
Initializes a GuidedNavigationDocument with a sequence of guided navigation objects.

### Method
Initializer

### Parameters
- **guided** ([GuidedNavigationObject]) - Required - A sequence of resources and/or media fragments into these resources, meant to be presented sequentially to the user.

### Return Value
A new GuidedNavigationDocument instance.
```

--------------------------------

### func start(with: AudioSessionUser, isPlaying: Bool)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/audiosessionmanaging

Starts a new audio session with the given user and playing state.

```APIDOC
## func start(with: AudioSessionUser, isPlaying: Bool)

### Description
Starts a new audio session with the given `user`.

### Method
func start(with user: AudioSessionUser, isPlaying: Bool)

### Parameters
- **user** (AudioSessionUser) - The user for whom to start the audio session.
- **isPlaying** (Bool) - Indicates whether the user is playing.

### Required
Yes
```

--------------------------------

### Create and start PublicationSpeechSynthesizer

Source: https://readium.org/swift-toolkit/latest/documentation/readium/tts

Creates a PublicationSpeechSynthesizer with a French default language, then starts playback from the beginning of the publication. The constructor returns an optional because not all publications can be read aloud; check canSpeak(publication:) beforehand if needed. The start() call begins speaking utterances from the start unless a starting Locator is provided.

```swift
let synthesizer = PublicationSpeechSynthesizer(
    publication: publication,
    config: PublicationSpeechSynthesizer.Configuration(
        defaultLanguage: Language("fr")
    )
)

```

```swift
synthesizer.start()

```

--------------------------------

### start

Source: https://readium.org/swift-toolkit/latest/documentation/readiumlcp/rights/start

The `start` property is an optional Date that specifies when the license begins. It is part of the ReadiumLCP Rights model and can be accessed as a read-only property.

```APIDOC
## start

### Description
Date and time when the license begins.

### Declaration
```swift
let start: Date?
```

### Parameters
- **start** (Date?) - Optional - The date and time when the license begins.
```

--------------------------------

### BasicStringSearchAlgorithm.init()

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/basicstringsearchalgorithm

Initializes a new instance of BasicStringSearchAlgorithm.

```APIDOC
## BasicStringSearchAlgorithm.init()

### Description
Initializes a new instance of BasicStringSearchAlgorithm.

### Method
init

### Parameters
None

### Return Value
A new BasicStringSearchAlgorithm instance.
```

--------------------------------

### static let example: GuidedNavigationObject.Role

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/guidednavigationobject/role/example

A type property that defines the 'example' role for a Guided Navigation Object, indicating an illustration of the usage of a defined term or phrase.

```APIDOC
## static let example: GuidedNavigationObject.Role

### Description
A type property that defines the 'example' role for a Guided Navigation Object, indicating an illustration of the usage of a defined term or phrase.

### Declaration
```swift
static let example: GuidedNavigationObject.Role
```

### Discussion
This property is part of the `GuidedNavigationObject.Role` enumeration and is used to specify that a navigation object serves as an example illustrating the usage of a defined term or phrase.

```

--------------------------------

### var localizedTitle: String { get }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/accessibilitydisplayfield/localizedtitle

A required, read-only instance property that returns a localized title for the display field, for example to use as a section header.

```APIDOC
## var localizedTitle: String { get }

### Description
Localized title for this display field, for example to use as a section header.

### Declaration
```swift
var localizedTitle: String { get }
```

### Properties
- **localizedTitle** (String) - Required - A localized title for the display field.

### Return Value
A localized title string for the display field.
```

--------------------------------

### func url(parameters: [String : LosslessStringConvertible]) -> HTTPURL?

Source: https://readium.org/swift-toolkit/latest/documentation/readiumlcp/link

Gets the valid URL if possible, applying the given template context as query parameters if the link is templated. For example, http://url{?id,name} with parameters [id: x, name: y] becomes http://url?id=x&name=y.

```APIDOC
## func url(parameters: [String : LosslessStringConvertible]) -> HTTPURL?

### Description
Gets the valid URL if possible, applying the given template context as query parameters if the link is templated. For example, http://url{?id,name} with parameters [id: x, name: y] becomes http://url?id=x&name=y.

### Method
Instance Method

### Parameters
- **parameters** ([String : LosslessStringConvertible]) - Required - The template context to apply.

### Return Value
An HTTPURL? representing the valid URL, or nil if not possible.
```

--------------------------------

### Instantiate AudioNavigator and play

Source: https://readium.org/swift-toolkit/latest/documentation/readium/navigator

Creates an AudioNavigator and starts playback. The AudioNavigator is chromeless and provides no user interface, so you must build your own custom UI.

```swift
let navigator = AudioNavigator(
    publication: publication,
    initialLocation: lastReadLocation
)


navigator.play()

```

--------------------------------

### init(preferences:defaults:playbackRefreshInterval:audioSession:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/audionavigator/configuration

Initializes a new AudioNavigator.Configuration instance with the provided preferences, defaults, playback refresh interval, and audio session configuration.

```APIDOC
## init(preferences:defaults:playbackRefreshInterval:audioSession:)

### Description
Initializes a new AudioNavigator.Configuration instance with the provided preferences, defaults, playback refresh interval, and audio session configuration.

### Method
Initializer

### Parameters
- **preferences** (AudioPreferences) - The initial set of setting preferences.
- **defaults** (AudioDefaults) - Provides default fallback values and ranges for the user settings.
- **playbackRefreshInterval** (TimeInterval) - Interval between two updates of the playback state.
- **audioSession** (AudioSession.Configuration) - Custom configuration for the audio session.

```

--------------------------------

### var sourceURL: AbsoluteURL? { get }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/directorycontainer/sourceurl

A read-only property that returns the URL locating this container, when available. It can be used to optimize access to the container's content, for example by using a file handle instead of the Container API. The URL must represent the same content as the Container, and becomes nil if the content is transformed on the fly.

```APIDOC
## var sourceURL: AbsoluteURL? { get }

### Description
Returns the URL locating this container, when available. This can be used to optimize access to the container's content for the caller. For example, if the container is available on the local file system, a caller might prefer using a file handle instead of the `Container` API.

### Property
`var sourceURL: AbsoluteURL? { get }`

### Return Value
An optional `AbsoluteURL` representing the location of the container, or `nil` if not available or if the content is transformed on the fly.

### Discussion
This property must represent the same content available in `Container`. If you transform the resources content on the fly (e.g. with `TransformingContainer`), then the `sourceURL` becomes `nil`.
```

--------------------------------

### init(client:licenseRepository:passphraseRepository:assetRetriever:httpClient:deviceName:deviceId:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumlcp/lcpservice

Initializes an LCPService instance with the required dependencies.

```APIDOC
## `init(client: LCPClient, licenseRepository: LCPLicenseRepository, passphraseRepository: LCPPassphraseRepository, assetRetriever: AssetRetriever, httpClient: HTTPClient, deviceName: String?, deviceId: String?)`

### Description
Initializes an LCPService instance with the required dependencies.

### Parameters
- **client** (LCPClient) - Required - The LCP client used for cryptographic operations.
- **licenseRepository** (LCPLicenseRepository) - Required - Repository for storing and retrieving LCP licenses.
- **passphraseRepository** (LCPPassphraseRepository) - Required - Repository for storing and retrieving passphrases.
- **assetRetriever** (AssetRetriever) - Required - Retrieves assets from URLs.
- **httpClient** (HTTPClient) - Required - HTTP client for network requests.
- **deviceName** (String?) - Optional - The name of the device.
- **deviceId** (String?) - Optional - The unique identifier of the device.
```

--------------------------------

### get(_:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/generatedcoverservice/get%28_%3A%29-1arpr

Documentation for the `get(_:)` instance method of `GeneratedCoverService` in ReadiumShared.

```APIDOC
## get(_:)

### Description
Returns a `Resource` for a given URL, or `nil` if the service does not recognize the request. This method is called by `Publication.get()` for each request and can be used to respond to web API requests, serve additional resources, or replace publication resources.

### Method
`func get<T>(_ href: T) -> Resource? where T : URLConvertible`

### Parameters
- **href** (T) - The URL to resolve, conforming to `URLConvertible`.

### Return Value
- **Resource?** - The `Resource` containing the response, or `nil` if the service doesn’t recognize this request.

### Discussion
- Respond to a request to its web API declared in links.
- Serve additional resources on behalf of the publication.
- Replace a publication resource by its own version.
```

--------------------------------

### init(after:before:highlight:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/locator/text-swift.struct/init%28after%3Abefore%3Ahighlight%3A%29

Initializes a new Locator.Text instance with optional context strings for after, before, and highlight.

```APIDOC
## init(after:before:highlight:)

### Description
Initializes a new Locator.Text instance with optional context strings for after, before, and highlight.

### Method
Initializer

### Signature
```swift
init(
    after: String? = nil,
    before: String? = nil,
    highlight: String? = nil
)
```

### Parameters
- **after** (String?) - Optional - Text that appears after the highlighted text.
- **before** (String?) - Optional - Text that appears before the highlighted text.
- **highlight** (String?) - Optional - The highlighted text itself.
```

--------------------------------

### start(from:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/publicationspeechsynthesizer/start%28from%3A%29

Starts or restarts the speech synthesizer from the given locator or the beginning of the publication.

```APIDOC
## start(from:)

### Description
(Re)starts the synthesizer from the given locator or the beginning of the publication.

### Method
`func start(from startLocator: Locator? = nil)`

### Parameters
- **startLocator** (Locator?) - Optional - The locator from which to start. If nil, starts from the beginning.

### Return Value
None (Void)

```

--------------------------------

### init()

Source: https://readium.org/swift-toolkit/latest/documentation/readiumlcp/lcpkeychainlicenserepository/init%28%29

Initializes a Keychain-based license repository.

```APIDOC
## init()

### Description
Initializes a Keychain-based license repository.

### Method
init

### Endpoint
init()

### Parameters
None

### Request Example
None

### Response
#### Success Response
None

#### Response Example
None

ERROR HANDLING:
- No error handling specified.
```

--------------------------------

### init?<T>(json:warnings:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/epubmediaoverlay

Initializes an EPUBMediaOverlay instance from a JSON value, with optional warnings.

```APIDOC
## init?<T>(json:warnings:)

### Description
Initializes an EPUBMediaOverlay instance from a JSON value, with optional warnings.

### Method
init

### Parameters
- **json** (T?) - Required - The JSON value to decode.
- **warnings** (WarningLogger?) - Optional - A logger for warnings during decoding.

### Return Value
An optional EPUBMediaOverlay instance, or nil if decoding fails.
```

--------------------------------

### init(context:metadata:links:readingOrder:resources:tableOfContents:subcollections:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/manifest

Initializes a Manifest with the given context, metadata, links, reading order, resources, table of contents, and subcollections.

```APIDOC
## init(context:metadata:links:readingOrder:resources:tableOfContents:subcollections:)

### Description
Initializes a Manifest with the provided components.

### Method
Initializer

### Parameters
- **context** ([String]) - Required - The JSON-LD context URLs.
- **metadata** (Metadata) - Required - The publication metadata.
- **links** ([Link]) - Required - The list of links.
- **readingOrder** ([Link]) - Required - The list of resources in reading order.
- **resources** ([Link]) - Required - The list of resources necessary for rendering.
- **tableOfContents** ([Link]) - Required - The list of links for the table of contents.
- **subcollections** ([String : [PublicationCollection]]) - Required - The subcollections keyed by name.
```

--------------------------------

### content(from:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/publication/content%28from%3A%29

Creates a `Content` starting from the given `start` location, or the beginning of the publication when missing.

```APIDOC
## content(from:)

### Description
Creates a `Content` starting from the given `start` location, or the beginning of the publication when missing.

### Method
Instance Method

### Endpoint
`func content(from start: Locator? = nil) -> Content?`

### Parameters
#### Parameters
- **start** (Locator?) - Optional - The starting location for the content. Defaults to `nil`, which means the beginning of the publication.

### Return Value
- **Content?** - An optional `Content` object representing the content starting from the specified location, or `nil` if not available.

### Example
```swift
let content = publication.content(from: startLocator)
```
```

--------------------------------

### init(id:locator:style:userInfo:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/decoration

Initializes a new Decoration with the given identifier, locator, style, and user info.

```APIDOC
## init(id:locator:style:userInfo:)

### Description
Initializes a new Decoration with the given identifier, locator, style, and user info.

### Method
init

### Parameters
- **id** (Id) - Required - An identifier for this decoration. It must be unique in the group the decoration is applied to.
- **locator** (Locator) - Required - Location in the publication where the decoration will be rendered.
- **style** (Style) - Required - Declares the look and feel of the decoration.
- **userInfo** ([AnyHashable : AnyHashable]) - Required - Additional context data specific to a reading app. Readium does not use it.

```

--------------------------------

### StatusError.expired(start:end:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumlcp/statuserror/expired%28start%3Aend%3A%29

A case of the StatusError enum indicating that the license started and expired on the given dates.

```APIDOC
## StatusError.expired(start:end:)

### Description
This license started and expired on the given dates.

### Declaration
```swift
case expired(
    start: Date,
    end: Date
)
```

### Parameters
- **start** (Date) - The start date of the license.
- **end** (Date) - The end date of the license.
```

--------------------------------

### init(activeClass:playbackActiveClass:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/epubmediaoverlay/init%28activeclass%3Aplaybackactiveclass%3A%29

Initializes an EPUBMediaOverlay instance with optional CSS class names for active and playback-active states.

```APIDOC
## init(activeClass:playbackActiveClass:)

### Description
Initializes an EPUBMediaOverlay instance with optional CSS class names for active and playback-active states.

### Method
Initializer

### Signature
```
init(
    activeClass: String? = nil,
    playbackActiveClass: String? = nil
)
```

### Parameters
- **activeClass** (String?) - Optional - The CSS class name applied to the active media overlay element.
- **playbackActiveClass** (String?) - Optional - The CSS class name applied to the element during playback.

```

--------------------------------

### var playback: Playback { get set }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/nowplayinginfo/playback-swift.property

Gets or sets the playback information about the rendition of the current media.

```APIDOC
## Property: playback

### Description
Playback information about the rendition of the current media.

### Declaration
```swift
var playback: Playback { get set }
```

### Parameters
- **playback** (Playback) - The playback information to set.

### Return Value
- **Playback** - The current playback information.

```

--------------------------------

### var speed: Double? { get set }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/audiopreferences/speed

Gets or sets the speed of playback. Normal speed is 1.0.

```APIDOC
## Property: speed

### Description
Speed of playback. Normal is 1.0.

### Declaration
```swift
var speed: Double? { get set }
```

### Parameters
- **speed** (Double?) - Optional - The playback speed value. A value of 1.0 represents normal speed.

### Return Value
- **Double?** - The current playback speed, or nil if not set.

### Discussion
This property is part of AudioPreferences and can be read and set to control playback speed.
```

--------------------------------

### setupLogger(logger:withMinimumSeverityLevel:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/logger/setuplogger%28logger%3Awithminimumseveritylevel%3A%29

Sets up the active logger and optionally the minimum severity level. See activeLogger for more information.

```APIDOC
## setupLogger(logger:withMinimumSeverityLevel:)

### Description
Sets up the active logger and optionally the minimum severity level. See `activeLogger` for more information.

### Method
Instance Method

### Signature
```swift
func setupLogger(
    logger: LoggerType,
    withMinimumSeverityLevel severityLevel: SeverityLevel? = .warning
)
```

### Parameters
- **logger** (LoggerType) - Required - The logger to be used as the `activeLogger`.
- **severityLevel** (SeverityLevel?) - Optional - The minimum severity level of displayed logs. Defaults to `.warning`.

```

--------------------------------

### var fontFamily: FontFamily { get }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/anyhtmlfontfamilydeclaration/fontfamily

Gets the name of the font family. This value corresponds to the `fontFamily` EPUB preference.

```APIDOC
## Property: fontFamily

### Description
Gets the name of the font family. This is the value of the `fontFamily` EPUB preference.

### Declaration
```swift
var fontFamily: FontFamily { get }
```

### Parameters
None

### Return Value
- **fontFamily** (FontFamily) - The name of the font family.

```

--------------------------------

### init(publication:config:audioSessionConfig:audioSession:engineFactory:tokenizerFactory:delegate:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/publicationspeechsynthesizer/init%28publication%3Aconfig%3Aaudiosessionconfig%3Aaudiosession%3Aenginefactory%3Atokenizerfactory%3Adelegate%3A%29

Initializer for creating a PublicationSpeechSynthesizer with configurable audio session, engine factory, tokenizer factory, and delegate.

```APIDOC
## init(publication:config:audioSessionConfig:audioSession:engineFactory:tokenizerFactory:delegate:)

### Description
Creates a `PublicationSpeechSynthesizer` using the given `TTSEngine` factory. Returns null if the publication cannot be synthesized.

### Method
Initializer

### Parameters
- **publication** (Publication) - Required - Publication which will be iterated through and synthesized.
- **config** (Configuration) - Optional - Initial TTS configuration. Defaults to `Configuration()`.
- **audioSessionConfig** (AudioSession.Configuration) - Optional - Configuration of the audio session used to play the utterances. Defaults to `.init(category: .playback, mode: .spokenAudio, routeSharingPolicy: .longFormAudio)`.
- **audioSession** (AudioSessionManaging) - Optional - Audio session manager used to coordinate playback. Defaults to `AudioSession.shared`.
- **engineFactory** (@escaping EngineFactory) - Optional - Factory to create an instance of `TtsEngine`. Defaults to `{ AVTTSEngine() }`.
- **tokenizerFactory** (@escaping TokenizerFactory) - Optional - Factory to create a `ContentTokenizer` which will be used to split each `ContentElement` item into smaller chunks. Defaults to `defaultTokenizerFactory` (splits by sentences).
- **delegate** (PublicationSpeechSynthesizerDelegate?) - Optional - Optional delegate.

### Return Value
Returns null if the publication cannot be synthesized.

### Discussion
Returns null if the publication cannot be synthesized.
```

--------------------------------

### var title: String? { get }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumfuzi/htmldocument/title

Gets the HTML title of the current document. Returns nil if no title is present.

```APIDOC
## Property: `title`

### Description
Gets the HTML title of the current document. Returns nil if no title is present.

### Declaration
```swift
var title: String? { get }
```

### Parameters
None

### Return Value
- **String?** - The HTML title of the document, or nil if not available.

### Example
```swift
let document = HTMLDocument(...)
if let title = document.title {
    print("Title: \(title)")
} else {
    print("No title")
}
```
```

--------------------------------

### init()

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/loggerstub

Initializes a new instance of LoggerStub.

```APIDOC
## init()

### Description
Initializes a new instance of LoggerStub.

### Method
init

### Parameters
None

### Response
No return value.
```

--------------------------------

### func content(from: Locator?) -> Content?

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/contentservice

Creates a Content starting from the given start location. This is a required method for conforming types.

```APIDOC
## func content(from: Locator?) -> Content?

### Description
Creates a `Content` starting from the given `start` location.

### Method
`content(from:)`

### Parameters
- **start** (`Locator?`) - The starting location from which to extract content. Optional.

### Return Value
- `Content?` - The extracted content, or `nil` if not available.

### Protocol
`ContentService`

### Requirements
Required

### Conforming Types
- `DefaultContentService`
```

--------------------------------

### init(directory:options:) async throws

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/directorycontainer

Creates a DirectoryContainer at the given directory serving all its children recursively.

```APIDOC
## init(directory: FileURL, options: FileManager.DirectoryEnumerationOptions) async throws

### Description
Creates a DirectoryContainer at `directory` serving all its children recursively.

### Parameters
- **directory** (FileURL) - The file system directory to serve.
- **options** (FileManager.DirectoryEnumerationOptions) - Options for enumerating the directory contents.

### Throws
An error if the directory cannot be enumerated.

### Return Value
A DirectoryContainer instance.
```

--------------------------------

### var resultCount: Int? { get }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/searchiterator/resultcount

Gets the number of matches for this search, if known. The count may be updated after each call to next().

```APIDOC
## var resultCount: Int? { get }

### Description
Number of matches for this search, if known.

### Declaration
```swift
var resultCount: Int? { get }
```

### Discussion
Depending on the search algorithm, it may not be possible to know the result count until reaching the end of the publication. The count might be updated after each call to `next()`.
```

--------------------------------

### init(tint:isActive:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/decoration/style-swift.struct/highlightconfig

Initializes a HighlightConfig with a tint color and active state.

```APIDOC
## init(tint:isActive:)

### Description
Initializes a HighlightConfig with a tint color and active state.

### Declaration
```swift
init(tint: UIColor?, isActive: Bool)
```

### Parameters
- **tint** (UIColor?) - The tint color for the highlight.
- **isActive** (Bool) - Whether the highlight is active.

```

--------------------------------

### init(httpClient:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/assetretriever

Creates an AssetRetriever with the default components.

```APIDOC
## init(httpClient:)

### Description
Creates an AssetRetriever with the default components.

### Method
init

### Parameters
- **httpClient** (HTTPClient) - Required - The HTTP client to use.

### Response
Returns an AssetRetriever instance.
```

--------------------------------

### var credentials: String? { get }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/contentprotectionservice/credentials-7la7c

Gets the credentials used to unlock the publication. This property is read-only and returns an optional string.

```APIDOC
## var credentials: String? { get }

### Description
Gets the credentials used to unlock this `Publication`. If provided, reading apps may store the credentials in a secure location to reuse them the next time the user opens the publication.

### Declaration
```swift
var credentials: String? { get }
```

### Discussion
If provided, reading apps may store the credentials in a secure location, to reuse them the next time the user opens the publication.
```

--------------------------------

### var pageSpacing: Double? { get set }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/pdfpreferences/pagespacing

Gets or sets the spacing between pages in points. This property is part of the PDFPreferences configuration.

```APIDOC
## pageSpacing

### Description
Spacing between pages in points.

### Declaration
```swift
var pageSpacing: Double? { get set }
```

### Property Details
- **Type**: `Double?`
- **Access**: Read-write (get set)
- **Default**: `nil` (no explicit spacing)

### Usage Example
```swift
preferences.pageSpacing = 10.0
let spacing = preferences.pageSpacing
```
```

--------------------------------

### init(text:img:audio:video:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/guidednavigationobject/refs-swift.struct/init%28text%3Aimg%3Aaudio%3Avideo%3A%29

Creates a Refs instance with optional media URLs. All parameters are optional and default to nil.

```APIDOC
## init(text:img:audio:video:)

### Description
Creates a Refs instance with optional media URLs. All parameters are optional and default to nil.

### Declaration
```swift
init?(
    text: AnyURL? = nil,
    img: AnyURL? = nil,
    audio: AnyURL? = nil,
    video: AnyURL? = nil
)
```

### Parameters
- **text** (AnyURL?) - Optional - URL for text content.
- **img** (AnyURL?) - Optional - URL for image content.
- **audio** (AnyURL?) - Optional - URL for audio content.
- **video** (AnyURL?) - Optional - URL for video content.

### Return Value
An optional Refs instance. Returns nil if initialization fails.
```

--------------------------------

### init(publication:start:resourceContentIteratorFactories:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/publicationcontentiterator

Initializes a PublicationContentIterator with a publication, an optional start locator, and a list of resource content iterator factories.

```APIDOC
## Initializer

### Description
Initializes a PublicationContentIterator with the given publication, optional start locator, and resource content iterator factories.

### Signature
`init(publication: Publication, start: Locator?, resourceContentIteratorFactories: [ResourceContentIteratorFactory])`

### Parameters
- **publication** (Publication) - The publication to iterate over.
- **start** (Locator?) - Optional starting locator.
- **resourceContentIteratorFactories** ([ResourceContentIteratorFactory]) - Factories for creating media type-specific iterators.
```

--------------------------------

### init(requiredExtensions:allowedExtensions:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/zabformatsniffer

Initializes a ZABFormatSniffer with required and allowed file extensions.

```APIDOC
## init(requiredExtensions:allowedExtensions:)

### Description
Initializes a ZABFormatSniffer with the given required and allowed file extensions.

### Method
init

### Parameters
- **requiredExtensions** (Set<FileExtension>) - Required - The set of file extensions required for an archive to be considered an audiobook.
- **allowedExtensions** (Set<FileExtension>) - Required - The set of file extensions allowed in an audiobook.

### Return Value
A new ZABFormatSniffer instance.
```

--------------------------------

### init(from:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/epubpreferences

Initializes an EPUBPreferences instance by decoding from a decoder.

```APIDOC
## init(from:)

### Description
Creates an `EPUBPreferences` instance by decoding from a decoder.

### Method
Initializer

### Parameters
- **from** (any Decoder) - Required - The decoder to read data from.

### Response
No return value.
```

--------------------------------

### init(hint:errorMessage:onSubmit:onForgotPassphrase:onCancel:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumlcp/lcpdialog/init%28hint%3Aerrormessage%3Aonsubmit%3Aonforgotpassphrase%3Aoncancel%3A%29

Initializes an LCPDialog with a hint, error message, and callbacks for submit, forgot passphrase, and cancel actions.

```APIDOC
## init(hint:errorMessage:onSubmit:onForgotPassphrase:onCancel:)

### Description
Initializes an LCPDialog view with an optional hint, an optional error message, and callbacks for user actions. The submit callback is required, while forgot passphrase and cancel callbacks are optional.

### Declaration
```swift
@MainActor
init(
    hint: String?,
    errorMessage: ErrorMessage?,
    onSubmit: @escaping (String) -> Void,
    onForgotPassphrase: (() -> Void)?,
    onCancel: (() -> Void)? = nil
)
```

### Parameters
- **hint** (String?) - Optional - A hint message to display in the dialog.
- **errorMessage** (ErrorMessage?) - Optional - An error message to display in the dialog.
- **onSubmit** (@escaping (String) -> Void) - Required - A closure called when the user submits, receiving the entered passphrase as a String.
- **onForgotPassphrase** (() -> Void)? - Optional - A closure called when the user requests a forgotten passphrase.
- **onCancel** (() -> Void)? - Optional - A closure called when the user cancels the dialog. Defaults to nil.

### Availability
- iOS 15.0+
- macOS 12.0+
- tvOS 15.0+
- watchOS 8.0+
```

--------------------------------

### get(_:) method signature

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/contentsearchservice/get%28_%3A%29

Declares the get(_:) method that returns an optional Resource for a URLConvertible href. Returns null if the service does not recognize the request.

```swift
func get<T>(_ href: T) -> Resource? where T : URLConvertible
```

--------------------------------

### var accessibilityLabel: String? { get }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/contentattributesholder/accessibilitylabel

Gets the accessibility label associated with the content attributes holder. This property is read-only and returns an optional string.

```APIDOC
## Property: accessibilityLabel

### Description
Gets the accessibility label associated with the content attributes holder.

### Declaration
```swift
var accessibilityLabel: String? { get }
```

### Parameters
None

### Return Value
- **String?** - An optional string representing the accessibility label, or nil if not set.

### Discussion
This property is part of the ContentAttributesHolder protocol and provides a way to access the accessibility label for the content.
```

--------------------------------

### init(id:config:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/decoration/style-swift.struct

Initializes a new Decoration.Style with a unique identifier and an optional configuration.

```APIDOC
## init(id:config:)

### Description
Initializes a new Decoration.Style with a unique identifier and an optional configuration.

### Method
init

### Parameters
- **id** (Id) - Required - Unique ID for the style.
- **config** (AnyHashable?) - Optional - Configuration for the style.

### Return Value
A new Decoration.Style instance.
```

--------------------------------

### init()

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/zipfoundationarchiveopener

Initializes a new ZIPFoundationArchiveOpener instance.

```APIDOC
## init()

### Description
Initializes a new ZIPFoundationArchiveOpener instance.

### Declaration
```swift
final class ZIPFoundationArchiveOpener
```

### Initializer
`init()`
```

--------------------------------

### content(from:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/contentservice/content%28from%3A%29

Creates a Content starting from the given start location. The implementation must be fast and non-blocking; actual extraction is done inside the Content implementation.

```APIDOC
## content(from:)

### Description
Creates a `Content` starting from the given `start` location. The implementation must be fast and non-blocking; actual extraction should be done inside the `Content` implementation.

### Method
content(from:)

### Parameters
- **start** (Locator?) - Optional - The starting location from which to create the content.

### Return Value
- **Content?** - Optional - The created content, or nil if not available.

### Discussion
The implementation must be fast and non-blocking. Do the actual extraction inside the `Content` implementation.
```

--------------------------------

### Requesting publication content from a locator

Source: https://readium.org/swift-toolkit/latest/documentation/readium/content

Initializes the content extraction process starting from a specific locator. If the locator is missing, extraction begins from the start of the publication.

```swift
guard let content = publication.content(from: startLocator) else {
    // Abort as the content cannot be extracted
    return
}
```

--------------------------------

### init(json:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/locatorcollection/init%28json%3A%29

Convenience initializer that discards warnings.

```APIDOC
## init(json:)

### Description
Convenience initializer that discards warnings.

### Method
Initializer

### Signature
```swift
init?<T>(json: T?) throws where T : JSONValueEncodable
```

### Parameters
- **json** (T?) - Optional - The JSON value to initialize from.

### Throws
- An error if the JSON cannot be decoded.

### Returns
An optional instance of `LocatorCollection`.
```

--------------------------------

### alignmentGuide(_:computeValue:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumlcp/lcpdialog/alignmentguide%28_%3Acomputevalue%3A%29-485wu

Sets the view's alignment guide for the specified vertical alignment, using a closure to compute the guide value from the view's dimensions.

```APIDOC
## alignmentGuide(_:computeValue:)

### Description
Sets the view's alignment guide for the specified vertical alignment, using a closure to compute the guide value from the view's dimensions.

### Method
Instance Method

### Declaration
```swift
@preconcurrency nonisolated
func alignmentGuide(
    _ g: VerticalAlignment,
    computeValue: @escaping (ViewDimensions) -> CGFloat
) -> some View
```

### Parameters
- **g** (VerticalAlignment) - The vertical alignment to set the guide for.
- **computeValue** (closure) - A closure that takes a `ViewDimensions` value and returns a `CGFloat` representing the guide value.

### Return Value
A view with the custom alignment guide applied.

### Availability
iOS 13.0+, iPadOS 13.0+, Mac Catalyst 13.0+, macOS 10.15+, tvOS 13.0+, watchOS 6.0+
```

--------------------------------

### init(string:) initializer signature

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/anyurl/init%28string%3A%29

Initializes an AnyURL from a string. Returns nil if the string cannot be converted to a valid URL.

```swift
init?(string: String)
```

--------------------------------

### init(layout:width:element:stylesheet:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/htmldecorationtemplate/init%28layout%3Awidth%3Aelement%3Astylesheet%3A%29-4fiz9

Initializes an HTML decoration template with layout, width, element closure, and optional stylesheet.

```APIDOC
## init(layout:width:element:stylesheet:)

### Description
Creates an HTML decoration template with the specified layout, width, element closure, and optional stylesheet.

### Method
Initializer

### Endpoint
`init(layout:width:element:stylesheet:)`

### Parameters
- **layout** (`Layout`) - Required - The layout type for the decoration template.
- **width** (`Width`) - Optional - The width of the decoration. Defaults to `.wrap`.
- **element** (`@escaping (Decoration) -> String`) - Optional - A closure that takes a `Decoration` and returns an HTML string. Defaults to `{ _ in "<div/>" }`.
- **stylesheet** (`String?`) - Optional - The stylesheet to apply. Defaults to `nil`.

### Request Example
```swift
HTMLDecorationTemplate(
    layout: .horizontal,
    width: .wrap,
    element: { decoration in
        return "<span>\(decoration.id)</span>"
    },
    stylesheet: "span { color: red; }"
)
```

### Response
#### Success Response
No return value. The initializer creates an `HTMLDecorationTemplate` instance.

#### Response Example
```swift
let template = HTMLDecorationTemplate(
    layout: .horizontal,
    width: .wrap,
    element: { _ in "<div/>" },
    stylesheet: nil
)
```
```

--------------------------------

### Start TTS from visible page with firstVisibleElementLocator()

Source: https://readium.org/swift-toolkit/latest/documentation/readium/tts

Starts the PublicationSpeechSynthesizer from the currently visible page in a VisualNavigator. Use this to begin TTS playback aligned with the page the user is viewing.

```swift
if let start = await navigator.firstVisibleElementLocator() {
    synthesizer.start(from: start)
}

```

--------------------------------

### init(data:sourceURL:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/dataresource/init%28data%3Asourceurl%3A%29

Creates a Resource serving an array of bytes. This convenience initializer takes a data closure and an optional source URL.

```APIDOC
## init(data:sourceURL:)

### Description
Creates a `Resource` serving an array of bytes.

### Method
Initializer

### Signature
```swift
convenience init(
    data: @autoclosure @escaping () -> Data,
    sourceURL: AbsoluteURL? = nil
)
```

### Parameters
- **data** (@autoclosure @escaping () -> Data) - Required - The data to be served by the resource.
- **sourceURL** (AbsoluteURL?) - Optional - The source URL of the resource. Defaults to nil.
```

--------------------------------

### Convert Foundation URL to typed URLs

Source: https://readium.org/swift-toolkit/latest/documentation/readium/migration-guide

Converts an existing Foundation URL to the new typed URL variants. Use url.fileURL to get a FileURL and url.httpURL to get an HTTPURL.

```swift
let url: URL
url.fileURL
url.httpURL

```

--------------------------------

### func httpClient(_:willStartRequest:) async -> HTTPResult<HTTPRequestConvertible>

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/defaulthttpclientdelegate/httpclient%28_%3Awillstartrequest%3A%29-16hyp

Tells the delegate that the HTTP client will start a new request. The delegate can modify the request before it is sent and must call the completion handler with the request to start.

```APIDOC
## httpClient(_:willStartRequest:)

### Description
Tells the delegate that the HTTP client will start a new `request`. The delegate can modify the request, for example by adding additional HTTP headers or redirecting to a different URL, before calling the completion handler with the new request.

### Method
Instance Method

### Signature
```swift
func httpClient(
    _ httpClient: DefaultHTTPClient,
    willStartRequest request: HTTPRequest
) async -> HTTPResult<HTTPRequestConvertible>
```

### Parameters
- **httpClient** (DefaultHTTPClient) - The HTTP client that will start the request.
- **request** (HTTPRequest) - The request that will be started.

### Return Value
- **HTTPResult<HTTPRequestConvertible>** - The result containing the request to start, possibly modified.

### Discussion
Warning: You MUST call the `completion` handler with the request to start, otherwise the client will hang.
You can modify the `request`, for example by adding additional HTTP headers or redirecting to a different URL, before calling the `completion` handler with the new request.
```

--------------------------------

### init(assetRetriever:manifestAugmentor:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumstreamer/audioparser

Initializes an AudioParser instance with the provided asset retriever and manifest augmentor.

```APIDOC
## init(assetRetriever:manifestAugmentor:)

### Description
Initializes an `AudioParser` instance with the provided asset retriever and manifest augmentor.

### Parameters
- **assetRetriever** (AssetRetriever) - Required - The retriever used to fetch assets for parsing.
- **manifestAugmentor** (AudioPublicationManifestAugmentor) - Required - The augmentor used to enhance the audio publication manifest.

### Declaration
```swift
init(assetRetriever: AssetRetriever, manifestAugmentor: AudioPublicationManifestAugmentor)
```
```

--------------------------------

### var credentials: String? { get }

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/contentprotectionservice/credentials

Gets the credentials used to unlock the Publication. If provided, reading apps may store the credentials in a secure location to reuse them the next time the user opens the publication.

```APIDOC
## var credentials: String? { get }

### Description
Credentials used to unlock this `Publication`.

### Declaration
swift
var credentials: String? { get }


### Discussion
If provided, reading apps may store the credentials in a secure location, to reuse them the next time the user opens the publication.

### Default Implementation
Provided by `ContentProtectionService` protocol extension.

### Implementations
- `var credentials: String?` - Credentials used to unlock this `Publication`.
```

--------------------------------

### Example pickerRow call for reading progression

Source: https://readium.org/swift-toolkit/latest/documentation/readium/preferences

Example call to pickerRow for a reading progression preference. Provides a formatValue closure that maps .ltr to "LTR" and .rtl to "RTL".

```swift
pickerRow(
    title: "Reading progression",
    preference: readingProgression,
    commit: commit,
    formatValue: { v in
        switch v {
        case .ltr: return "LTR"
        case .rtl: return "RTL"
        }
    }
)

```

--------------------------------

### init(resource:mediaType:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/httpserverresponse/init%28resource%3Amediatype%3A%29

Initializes an HTTPServerResponse with a given resource and optional media type. Use this to create a response object for serving a resource over HTTP.

```APIDOC
## init(resource:mediaType:)

### Description
Initializes an HTTPServerResponse with a given resource and optional media type.

### Method
Initializer

### Signature
```swift
init(
    resource: Resource,
    mediaType: MediaType?
)
```

### Parameters
- **resource** (Resource) - Required - The resource to be served.
- **mediaType** (MediaType?) - Optional - The media type of the resource. Pass nil if unknown.

### Return Value
An HTTPServerResponse instance.
```

--------------------------------

### init(summary:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/accessibilitymetadatadisplayguide/accessibilitysummary-swift.struct/init%28summary%3A%29

Creates an AccessibilitySummary instance with an optional summary string.

```APIDOC
## init(summary:)

### Description
Initializes an AccessibilitySummary instance with an optional summary string.

### Declaration
```swift
init(summary: String? = nil)
```

### Parameters
- **summary** (String?) - Optional - The summary text to associate with the accessibility metadata.
```

--------------------------------

### entries

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/singleresourcecontainer/entries

Gets the list of all container entries.

```APIDOC
## entries

### Description
Returns a set of all container entries.

### Declaration
```swift
var entries: Set<AnyURL> { get }
```

### Parameters
None.

### Return Value
A set of `AnyURL` objects representing the container entries.
```

--------------------------------

### init(resources:progression:positions:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/navigatorviewport

Initializes a new NavigatorViewport with the specified visible resources, progression range, and optional positions range.

```APIDOC
## `init(resources: [Resource], progression: ClosedRange<Double>, positions: ClosedRange<Int>?)`

### Description
Initializes a new NavigatorViewport with the given visible resources, progression range, and optional positions range.

### Parameters
- **resources** (`[Resource]`) - Required - The visible reading order resources.
- **progression** (`ClosedRange<Double>`) - Required - The range of visible total progression in the publication (0.0–1.0).
- **positions** (`ClosedRange<Int>?`) - Optional - The range of visible positions in the publication's position list. Pass `nil` if positions are not available.

### Return Value
A new NavigatorViewport instance.
```

--------------------------------

### attributes(_:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/anyequatablecontentelement/attributes%28_%3A%29

Gets all the attributes with the given `key`.

```APIDOC
## attributes(_:)

### Description
Gets all the attributes with the given `key`.

### Method
attributes(_:)

### Parameters
- **key** (ContentAttributeKey<T>) - Required - The key for which to retrieve attributes.

### Return Value
- [T] - An array of attributes associated with the given key.

### Example
```swift
let attributes = element.attributes(someKey)
```
```

--------------------------------

### play()

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/audionavigator/play%28%29

Resumes or starts the playback of the audio content.

```APIDOC
## play()

### Description
Resumes or starts the playback.

### Method
`func play()`

### Parameters
None.

### Return Value
None.

### Example
```swift
navigator.play()
```
```

--------------------------------

### init(defaultLanguage:voiceIdentifier:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/publicationspeechsynthesizer/configuration/init%28defaultlanguage%3Avoiceidentifier%3A%29

Creates a configuration instance with optional default language and voice identifier.

```APIDOC
## init(defaultLanguage:voiceIdentifier:)

### Description
Initializes a new configuration for the PublicationSpeechSynthesizer with an optional default language and voice identifier.

### Method
Initializer

### Signature
```swift
init(
    defaultLanguage: Language? = nil,
    voiceIdentifier: String? = nil
)
```

### Parameters
- **defaultLanguage** (Language?) - Optional - The default language to use for speech synthesis.
- **voiceIdentifier** (String?) - Optional - The identifier of the voice to use for speech synthesis.

### Return Value
A new configuration instance.
```

--------------------------------

### subscript(_:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/textcontentelement/segment/subscript%28_%3A%29

Gets the first attribute with the given `key`.

```APIDOC
## subscript<T>(key: ContentAttributeKey<T>) -> T?

### Description
Gets the first attribute with the given `key`.

### Method
subscript

### Parameters
#### Parameters
- **key** (ContentAttributeKey<T>) - The key of the attribute to retrieve.

### Return Value
- **T?** - The value of the attribute if found, otherwise `nil`.

### Example
```swift
let value = segment[key]
```
```

--------------------------------

### init(from: any Decoder) throws

Source: https://readium.org/swift-toolkit/latest/documentation/readiumnavigator/textalignment/rawrepresentable-implementations

Initializes a TextAlignment instance by decoding from a decoder.

```APIDOC
## init(from: any Decoder) throws

### Description
Initializes a TextAlignment instance by decoding from a decoder.

### Method
Initializer

### Signature
`init(from: any Decoder) throws`

### Parameters
- **from** (any Decoder) - The decoder to read data from.

### Throws
An error if decoding fails.
```

--------------------------------

### get(_:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/publication/get%28_%3A%29-3z809

Returns the resource targeted by the given `href`.

```APIDOC
## get(_:)

### Description
Returns the resource targeted by the given `href`.

### Method
Instance Method

### Signature
```swift
func get<T>(_ href: T) -> Resource? where T : URLConvertible
```

### Parameters
- **href** (T) - The URL or URL convertible value that identifies the resource to retrieve.

### Return Value
- **Resource?** - The resource targeted by the given `href`, or `nil` if no resource is found.

### Discussion
Use this method to obtain a `Resource` object for a given `href` within the publication. The `href` parameter conforms to `URLConvertible`, allowing you to pass either a `URL` or a `String` that can be converted to a URL.
```

--------------------------------

### init([ArchiveOpener])

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/compositearchiveopener

Initializes a CompositeArchiveOpener with an array of ArchiveOpener factories to try in order.

```APIDOC
## init([ArchiveOpener])

### Description
Initializes a CompositeArchiveOpener with an array of ArchiveOpener factories to try in order.

### Declaration
`init([ArchiveOpener])`

### Parameters
- **openers** ([ArchiveOpener]) - The list of ArchiveOpener factories to try.
```

--------------------------------

### get(_:)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/publication/get%28_%3A%29-2l6g1

Returns the resource targeted by the given `link`.

```APIDOC
## get(_:)

### Description
Returns the resource targeted by the given `link`.

### Method
`func get(_ link: Link) -> Resource?`

### Parameters
- **link** (`Link`) - Required - The link whose target resource should be returned.

### Return Value
- `Resource?` - The resource targeted by the given link, or `nil` if not found.
```

--------------------------------

### init?(string: String)

Source: https://readium.org/swift-toolkit/latest/documentation/readiumshared/anyurl/init%28string%3A%29

Initializes an AnyURL instance from a string. Returns nil if the string is not a valid URL.

```APIDOC
## init?(string: String)

### Description
Initializes an AnyURL instance from a string. Returns nil if the string is not a valid URL.

### Declaration
```swift
init?(string: String)
```

### Parameters
- **string** (String) - The string to create the URL from.

### Return Value
An optional AnyURL instance, or nil if the string is not a valid URL.

### Inheritance
Inherited from `URLProtocol.init(string:)`.
```
Tokens:
Raw