# DTB compilation and packaging

The compiler converts an accepted book model and finalized audio into the files required by an approved NLS output profile. It should serialize typed data and enforce explicit rules. Generating final XML directly with an LLM would make exact compliance harder to control.

## What the main files do

| File or format | Role |
|---|---|
| OPF | Describes metadata, the package contents and reading/playback organization. |
| NCX | Defines navigable structures, labels and destinations. |
| SMIL | Connects ordered playback structures to particular media clips. |
| WAV masters | Accepted uncompressed source audio used as the timing reference. |
| AMR-WB+ in 3GP | Compressed audio with NLS-specific codec and container constraints. |
| Resource files | Supply approved alternative navigation-class labels when needed. |
| `dtb.md5` | XML checksum document for the DTB files, excluding itself. |
| DTD and entity files | Local dependencies needed to interpret and validate the XML. |

These descriptions summarize [J1 §§3.1–3.10](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/158655a84f024ae591f1b98e591bd801/download#page=9). Exact applicability depends on the selected profile.

## Freeze audio before final timing

**Proposal:** track positions as integer samples, complete approved mastering and assembly, then freeze the accepted WAV timeline. Derive clip timestamps from that final timeline, not from rough ASR estimates or an earlier synthesis chunk.

In attached J1 §3.2.5, timestamps remain relative to the accepted WAV; codec offset compensation is assigned to the player. Do not silently shift XML to encoded-audio timing or compensate twice. [J1 pp10–11](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/158655a84f024ae591f1b98e591bd801/download#page=10).

## Timing windows depend on clip type

<!-- diagram:timing -->

| Clip type | Start before speech | End after speech | Attachment source |
|---|---|---|---|
| Main SMIL narration clips | 80–120 ms | 150–300 ms | [J1 §3.3.4, p11](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/158655a84f024ae591f1b98e591bd801/download#page=11) |
| Heading labels | 80–120 ms | 150–300 ms | [J1 §3.4.5, p15](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/158655a84f024ae591f1b98e591bd801/download#page=15) |
| Alternative-class resource audio | 100–200 ms | 150–500 ms | [J3 §3.3.3, p8](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/48b52294c2f44f0780f220a9eff56cbd/download#page=8) |

The first two rows also require the boundaries to lie in silence. Both clip endpoints must be present. A shared global “navigation padding” constant would miss the resource exception.

Use alignment plus local waveform analysis to identify the actual speech boundary. If the required margin is unavailable, flag the case or make an approved audio edit and rebuild dependent timing. Choosing the middle of a permitted window is a proposed default, not an NLS rule.

## Main destinations and spoken labels

A navigation destination resolves into primary audio through SMIL. Its spoken label may refer to a different range in the headings audio. Keep both references explicit. Labels must represent the heading, not the whole section. [J1 §§3.4.3.4–3.4.3.5, pp13–14](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/158655a84f024ae591f1b98e591bd801/download#page=13); [J3 §3.1.2, p6](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/48b52294c2f44f0780f220a9eff56cbd/download#page=6).

J3 requires at least two level-one navPoints: the first marks the opening title/author with class `title/author`, and the last marks the closing announcement with class `close`. [J3 §3.1.1, p5](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/48b52294c2f44f0780f220a9eff56cbd/download#page=5).

Notes, note references, sidebars, pages, line numbers and segments need their own semantics. J3 requires segment navigation for entries in specified lists, and J1 says not to create navLists for segments. Treating every navigation object as a chapter loses these distinctions. [J3 §§3.2.1–3.2.4, pp6–7](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/48b52294c2f44f0780f220a9eff56cbd/download#page=6); [J1 §3.4.4, p14](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/158655a84f024ae591f1b98e591bd801/download#page=14).

## Exact rules from the attached construction edition

| Rule in J1 | Compiler consequence |
|---|---|
| No more than 250 files; §3.1.3 | Count all required files under that edition. The newer public edition differs. |
| Split SMIL above 100 KiB; at most 50 SMIL files; §3.3.12 | Measure actual UTF-8 serialized bytes; 100 KiB is 102,400 bytes. Follow the stated escalation rule if limits are exceeded. |
| At most 5,000 navPoints; contact monitor when exceeding 1,000; §3.4.3.6 | Distinguish a hard limit from a consultation trigger. |
| Lowercase filenames and prescribed production IDs/suffixes; §3.1 | Generate names from the profile and NLS-supplied identity. |
| XML `diskcheck` checksum structure; §3.9 | Ordinary `md5sum` text is insufficient. Include each file except the checksum itself; do not list the checksum in the OPF manifest. |
| Include referenced DTDs and entities; UTF-8 XML; §3.10 | Package dependencies and validate against an approved local catalog. |
| Duration follows SMIL playback, including specified custom-test content; §5.3(v) | Derive duration from the compiled playback structure, within the stated ±1 second accuracy. |

See [J1 pp9–20](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/158655a84f024ae591f1b98e591bd801/download#page=9). Do not apply the attached 250-file limit to a newer profile by accident. Permit only approved local XML dependencies; do not enable arbitrary network/entity resolution for book content.

## Encoding is an early interoperability risk

AMR-WB+ is not ordinary AMR-WB. Attached J1 specifies mono constant bitrate, frame type 23 and ISF index 8, plus particular 3GP metadata and field constraints. A file extension alone proves none of those properties. [J1 §3.2.3, p10](https://sam.gov/api/prod/opps/v3/opportunities/resources/files/158655a84f024ae591f1b98e591bd801/download#page=10).

[Hindenburg's support article](https://hindenburg.uservoice.com/knowledgebase/articles/1851514-narrator-nls-export-problem-could-not-locate-a) describes an NLS-supplied encoder; [APH's revision history](https://tech.aph.org/bwp_new.htm) records NLS protection/validation integration. These are historical precedents. Obtain current components, terms, supported operating systems, automation interfaces and cloud-deployment approval before relying on them.

## Protection is part of the book

PDTB protection involves protected content and associated authorization/key material. S3 storage encryption protects stored objects but does not create a protected talking book that an NLS player can authorize. See the [DAISY protection specification](https://daisy.org/activities/standards/pdtb/daisy-protected-digital-talking-book-specification/) and request the governing NLS 1205 profile and tooling.

## Packaging and final submission

The public **1206:2025** delivery specification describes an outer ZIP with protected/unprotected DTB archives and WAV masters. It specifies uncompressed entries and local-header CRC/size values with ZIP bit 3 clear. A seekable staging file is a proposed way to control those headers, followed by archive inspection and extracted-file checks. [Delivery specification §§3–3.2](https://www.loc.gov/nls/who-we-are/guidelines-and-specifications/contract-specifications/dtb-delivery-requirements/).

Its §4 names the **NLS Transfer Portal**. Internal S3 staging is a separate architectural choice; confirm the project-specific final interface. Keep QA logs outside the delivery package unless that interface expressly permits them.

## Reuse existing DAISY components selectively

[DAISY Pipeline's DTBook-to-DAISY3 script](https://daisy.github.io/pipeline/Get-Help/User-Guide/Scripts/dtbook-to-daisy3/) accepts a 2005-3 DTBook input and offers speech-related conversion options. It is a useful candidate for selected transformations. That documentation does not establish an NLS 2002, AMR-WB+, protected export path. Keep the NLS profile and acceptance tests explicit even when reusing its code.