Best practices for EPUB3—>DAISY with media overlay

[TypeflowNYC]

Hi there. I'm good at EPUB, but new to DAISY.

I'm getting EPUB validation errors in Pipeline 2 from files that pass EPUBcheck just fine, and "not found in fileset" errors for files that I can see are present in the EPUB. I'm also getting errors I don't understand about smil targets not matching spine order.

I'm also not sure how the MP3 should be specified for narration of each XHTML. Do the XHTML and PAR ids already have to be present in the EPUB, or is there a tool for that? (EPUB3 Enhancer seems to be for TTS, not for audio + .smil.)

Is there a best practices document somewhere?

Thanks!

[bertfrees]

Hi. There is no best practices document, and any valid EPUB 3 should pass the conversion without errors. Right now I haven't got an idea what could be the problem. I think the first step is for us to try to reproduce. Romain has already asked you if you could share an EPUB file with us. If that would be possible that would help a lot.

[bertfrees]

@TypeflowNYC @rdeltour When I try to validate the book with word-level media overlays that you emailed, using DAISY Pipeline (which uses EPUBCheck 4.2.5), I get a stack-overflow error. Perhaps it's because of the older version of EPUBCheck. I don't know. I thought it was worth mentioning.

The second observation is that the EPUB 3 to DAISY 3 conversion takes a very long time. I have done some optimizations to the code to speed up the conversion significantly. I can now convert your book with no issues (if validation is disabled). I did get "Found document in fileset that is neither stored on disk nor in memory" warnings. That was a bug, which I've fixed now.

Converting your book with the word-level media overlay spans removed to DAISY 3 also works like a charm.

When I try to convert the book to DAISY 2.02, the script fails because the input contains SMILs that reference sections that contain a heading. E.g. ata.smil references ata.xhtml#narration which contains the "About the Author" heading (h1 with id _idParaDest-38). The script currently can't handle this. DAISY 2.02 requires references to all headings from the NCC, and if the EPUB contains audio with text synchronization that is too coarse, the script chokes.

[TypeflowNYC]

I'm back to experimenting. How can I get that updated EPUB3 to DAISY 3 script? Thanks!

[TypeflowNYC]

Hello! Just checking in—how can I update Pipeline 2 scripts to their current versions? I'm not finding that information in the documentation. Thanks!

[TypeflowNYC]

OK, thank you and very much appreciated. Two followups: 1. What's the best practice when a SMIL references an XHTML that contains headings? Make the headings all <p> tags? 2. I have MP3s that should be used in the DAISY book but are not present in the EPUB, because the EPUB is strictly word-level, with one-to-one correspondence between text and audio, but the MP3s contain speech that doesn't appear in the book as text. What's the best way to handle this so Pipeline ingests it easily and DAISY readers play the MP3 when the appropriate XHTML is loaded? Thank you very much—

[bertfrees]

1. What's the best practice when a SMIL references an XHTML that contains headings? Make the headings all <p> tags?

I'm not sure. It needs to be possible for Pipeline to create a navigation document with links to all headings and page numbers. So the best situation is when the SMIL references the heading itself (or the words within the heading in case of word-level synchronization). The rest of the section may be unsynchronized, as long as it is possible to navigate to the heading. Making the headings into <p> sounds like a bad solution if we care about accessibility of the book.

In the particular case where a <h1> heading is at the very start of the section referenced by the SMIL, Pipeline could simply link to the section from the NCC. That would definitely be an improvement. I'm not sure if that would make it possible to convert your book though. Presumably the XHTML files could also contain lower level headings?

2. I have MP3s that should be used in the DAISY book but are not present in the EPUB.

I believe the recommendation is to have text-less placeholder elements in the HTML. This document seems relevant: https://daisy.org/info-help/guidance-training/standards/navigable-audio-only-epub3-guidelines/. Refer to "the recommended approaches for synchronizing partial text with audio".

[TypeflowNYC]

OK, thanks. What platform should I test the converted files on, and where can I learn what behavior is correct and expected on those platforms?

[bertfrees]

I don't currently have a platform to test on myself, but in the past we've tested mostly with Dolphin EasyReader (Windows) and VoiceDream Reader (iOS/Android).

[TypeflowNYC]

If you had to test on Macintosh, which is what I'm on (publishing runs on Mac), what platform would you reach for?

[bertfrees]

I don't know. I'm a Mac user myself and to test I've worked with a VM in the past.

[ManfredMuchenberger]

Dolphin just told us that there is EasyReader for Mac. But no free version.
I never used it so far - but worth a try as it is supposed to use the same code base as for the other OSs.

[ManfredMuchenberger]

Dolphin just told us, that there is EasyReader for Mac.
But no free version.
(never used it myself so far but woth to try as it is supposed to be the same code base as for the other platforms)

[TypeflowNYC]

Are there "known perfect" DAISY 3 and DAISY 2.02 files somewhere, so I can see what correct behavior looks like? I need some sort of benchmark to compare my files to. Thanks!

[bertfrees]

There are some samples files here: https://github.com/daisy/pipeline-samples.

[TypeflowNYC]

Thanks. Is there a tool to associate MP3 files with their corresponding parts of the book, or does everyone just code media overlays (smils, pars) into EPUBs manually and then run that through Pipeline?

[TypeflowNYC]

Thanks for all the help.

[gautierchomel]

Hello @TypeflowNYC Thorium Reader is cross platform and supports Daisy formats.

[TypeflowNYC]

Hi. Where does the EPUB3 —> DAISY 3 script expect to get these "Untitled" strings from in the EPUB?

Thank you!