Task 185: .EPUB File Format
Task 185: .EPUB File Format
EPUB File Format Specifications
The .EPUB file format is a standard for digital publications, defined by the EPUB 3.3 specification from the W3C. It is a ZIP-based container format that encapsulates HTML, CSS, XML, images, and other resources for e-books. The core structure is governed by the Open Container Format (OCF), which ensures interoperability. Key documents include the package document (.opf), navigation document, and content documents. The format supports reflowable and fixed-layout content, metadata, accessibility features, and media overlays.
- List of all the properties of this file format intrinsic to its file system:
- File extension: .epub
- MIME type: application/epub+zip
- Container format: ZIP archive (version 2.0 or higher, with ZIP64 extensions if needed; only stored or Deflate compression; no spanning, splitting, or ZIP encryption; file names encoded in UTF-8)
- mimetype file: Must be the first entry in the ZIP archive; path is "mimetype"; content is exactly "application/epub+zip" in US-ASCII with no padding, whitespace, or byte order mark; must be uncompressed (method 0) and have no extra fields in its ZIP header
- Container version: "1.0" (from the version attribute in container.xml)
- Rootfiles: List of rootfile entries from container.xml, each with a full-path (relative to root) and media-type (typically "application/oebps-package+xml" for the primary package document)
- Presence of signatures.xml: Yes/No (optional file in META-INF for digital signatures)
- Presence of encryption.xml: Yes/No (optional file in META-INF for encryption info, required if fonts are obfuscated)
- Presence of metadata.xml: Yes/No (optional file in META-INF for container metadata)
- Presence of rights.xml: Yes/No (optional file in META-INF for rights management)
- Presence of manifest.xml: Yes/No (optional file in META-INF for container manifest, for ODF compatibility)
These properties focus on the container-level structure and are extractable without processing the full publication content.
- Two direct download links for .EPUB files:
- https://www.gutenberg.org/ebooks/11.epub.noimages
- https://github.com/IDPF/epub3-samples/releases/download/20230704/accessible_epub_3.epub
- Ghost blog embedded HTML JavaScript for drag-and-drop .EPUB file to dump properties:
Drag and drop an .EPUB file here
This snippet can be embedded in a Ghost blog post. It uses JSZip for ZIP handling (loaded from CDN). Drag and drop an .EPUB file to display the properties in JSON format.
- Python class for .EPUB handling:
import zipfile
import xml.etree.ElementTree as ET
from io import BytesIO
class EpubHandler:
def __init__(self, filepath):
self.filepath = filepath
self.properties = {}
self._read_properties()
def _read_properties(self):
with zipfile.ZipFile(self.filepath, 'r') as zf:
infolist = zf.infolist()
if not infolist or infolist[0].filename != 'mimetype':
raise ValueError('mimetype not first file')
mimetype_info = infolist[0]
with zf.open(mimetype_info) as f:
mime_content = f.read().decode('ascii').strip()
self.properties = {
'file_extension': '.epub',
'mime_type': mime_content,
'container_format': 'ZIP',
'mimetype_file': {
'exists': True,
'content': mime_content,
'compression': 'uncompressed' if mimetype_info.compress_type == zipfile.ZIP_STORED else 'compressed',
'extra_fields': bool(mimetype_info.extra)
},
'container_version': '',
'rootfiles': [],
'signatures_xml': 'META-INF/signatures.xml' in zf.namelist(),
'encryption_xml': 'META-INF/encryption.xml' in zf.namelist(),
'metadata_xml': 'META-INF/metadata.xml' in zf.namelist(),
'rights_xml': 'META-INF/rights.xml' in zf.namelist(),
'manifest_xml': 'META-INF/manifest.xml' in zf.namelist()
}
if self.properties['mime_type'] != 'application/epub+zip':
raise ValueError('Invalid MIME type')
if 'META-INF/container.xml' not in zf.namelist():
raise ValueError('Missing container.xml')
with zf.open('META-INF/container.xml') as f:
container_content = f.read()
root = ET.fromstring(container_content)
ns = {'ocf': 'urn:oasis:names:tc:opendocument:xmlns:container'}
self.properties['container_version'] = root.get('version', '')
for rf in root.findall('.//ocf:rootfile', ns):
self.properties['rootfiles'].append({
'full_path': rf.get('full-path'),
'media_type': rf.get('media-type')
})
def print_properties(self):
import json
print(json.dumps(self.properties, indent=4))
def write_properties(self, new_properties, output_path=None):
if output_path is None:
output_path = self.filepath
with zipfile.ZipFile(self.filepath, 'r') as zf_in:
with zipfile.ZipFile(output_path, 'w') as zf_out:
# Write mimetype first
mimetype_content = new_properties.get('mime_type', 'application/epub+zip').encode('ascii')
zinfo = zipfile.ZipInfo('mimetype')
zinfo.compress_type = zipfile.ZIP_STORED
zinfo.external_attr = 0o644 << 16
zf_out.writestr(zinfo, mimetype_content)
# Update container.xml
container_content = self._generate_container_xml(new_properties)
zinfo = zipfile.ZipInfo('META-INF/container.xml')
zinfo.compress_type = zipfile.ZIP_DEFLATED
zinfo.external_attr = 0o644 << 16
zf_out.writestr(zinfo, container_content)
# Copy other files, adding/removing optional META-INF as needed
for item in zf_in.infolist():
if item.filename == 'mimetype' or item.filename == 'META-INF/container.xml':
continue
buffer = zf_in.read(item.filename)
zf_out.writestr(item, buffer)
# Add optional files if specified (dummy for simplicity)
for key, filename in [
('signatures_xml', 'META-INF/signatures.xml'),
('encryption_xml', 'META-INF/encryption.xml'),
('metadata_xml', 'META-INF/metadata.xml'),
('rights_xml', 'META-INF/rights.xml'),
('manifest_xml', 'META-INF/manifest.xml')
]:
if new_properties.get(key, False) and filename not in zf_in.namelist():
zf_out.writestr(filename, b'<!-- Dummy content -->')
def _generate_container_xml(self, props):
root = ET.Element('container', {'xmlns': 'urn:oasis:names:tc:opendocument:xmlns:container', 'version': props.get('container_version', '1.0')})
rootfiles = ET.SubElement(root, 'rootfiles')
for rf in props.get('rootfiles', []):
ET.SubElement(rootfiles, 'rootfile', {'full-path': rf['full_path'], 'media-type': rf['media_type']})
return ET.tostring(root, encoding='utf-8', xml_declaration=True)
# Example usage:
# handler = EpubHandler('example.epub')
# handler.print_properties()
# new_props = handler.properties.copy()
# new_props['container_version'] = '1.0'
# handler.write_properties(new_props, 'modified.epub')
This class opens an .EPUB, decodes and reads the properties, prints them to console in JSON, and can write modified properties to a new or same file (preserving other content).
- Java class for .EPUB handling:
import java.io.*;
import java.util.*;
import java.util.zip.*;
import javax.xml.parsers.*;
import org.w3c.dom.*;
import org.xml.sax.InputSource;
public class EpubHandler {
private String filepath;
private Map<String, Object> properties;
public EpubHandler(String filepath) throws Exception {
this.filepath = filepath;
this.properties = new HashMap<>();
readProperties();
}
private void readProperties() throws Exception {
try (ZipFile zf = new ZipFile(filepath)) {
Enumeration<? extends ZipEntry> entries = zf.entries();
if (!entries.hasMoreElements()) throw new Exception("Empty ZIP");
ZipEntry first = entries.nextElement();
if (!first.getName().equals("mimetype")) throw new Exception("mimetype not first file");
try (InputStream is = zf.getInputStream(first)) {
String mimeContent = new String(is.readAllBytes(), "US-ASCII").trim();
properties.put("file_extension", ".epub");
properties.put("mime_type", mimeContent);
properties.put("container_format", "ZIP");
Map<String, Object> mimetypeFile = new HashMap<>();
mimetypeFile.put("exists", true);
mimetypeFile.put("content", mimeContent);
mimetypeFile.put("compression", first.getMethod() == ZipEntry.STORED ? "uncompressed" : "compressed");
mimetypeFile.put("extra_fields", first.getExtra() != null && first.getExtra().length > 0);
properties.put("mimetype_file", mimetypeFile);
}
if (!properties.get("mime_type").equals("application/epub+zip")) throw new Exception("Invalid MIME type");
ZipEntry containerEntry = zf.getEntry("META-INF/container.xml");
if (containerEntry == null) throw new Exception("Missing container.xml");
try (InputStream is = zf.getInputStream(containerEntry)) {
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
DocumentBuilder db = dbf.newDocumentBuilder();
Document doc = db.parse(new InputSource(is));
Element root = doc.getDocumentElement();
properties.put("container_version", root.getAttribute("version"));
List<Map<String, String>> rootfiles = new ArrayList<>();
NodeList rfNodes = root.getElementsByTagName("rootfile");
for (int i = 0; i < rfNodes.getLength(); i++) {
Element rf = (Element) rfNodes.item(i);
Map<String, String> rfMap = new HashMap<>();
rfMap.put("full_path", rf.getAttribute("full-path"));
rfMap.put("media_type", rf.getAttribute("media-type"));
rootfiles.add(rfMap);
}
properties.put("rootfiles", rootfiles);
}
properties.put("signatures_xml", zf.getEntry("META-INF/signatures.xml") != null);
properties.put("encryption_xml", zf.getEntry("META-INF/encryption.xml") != null);
properties.put("metadata_xml", zf.getEntry("META-INF/metadata.xml") != null);
properties.put("rights_xml", zf.getEntry("META-INF/rights.xml") != null);
properties.put("manifest_xml", zf.getEntry("META-INF/manifest.xml") != null);
}
}
public void printProperties() {
System.out.println(propertiesToJson(properties));
}
private String propertiesToJson(Map<String, Object> props) {
// Simple JSON serialization for console
StringBuilder sb = new StringBuilder("{\n");
for (Map.Entry<String, Object> entry : props.entrySet()) {
sb.append(" \"").append(entry.getKey()).append("\": ");
if (entry.getValue() instanceof Map) {
sb.append(propertiesToJson((Map) entry.getValue()));
} else if (entry.getValue() instanceof List) {
sb.append(listToJson((List) entry.getValue()));
} else if (entry.getValue() instanceof String) {
sb.append("\"").append(entry.getValue()).append("\"");
} else {
sb.append(entry.getValue());
}
sb.append(",\n");
}
sb.setLength(sb.length() - 2); // Remove last comma
sb.append("\n}");
return sb.toString();
}
private String listToJson(List list) {
StringBuilder sb = new StringBuilder("[\n");
for (Object item : list) {
if (item instanceof Map) {
sb.append(" ").append(propertiesToJson((Map) item)).append(",\n");
}
}
if (!list.isEmpty()) sb.setLength(sb.length() - 2);
sb.append("\n ]");
return sb.toString();
}
public void writeProperties(Map<String, Object> newProperties, String outputPath) throws Exception {
if (outputPath == null) outputPath = filepath;
try (ZipFile zfIn = new ZipFile(filepath);
ZipOutputStream zos = new ZipOutputStream(new FileOutputStream(outputPath))) {
// Write mimetype first
String mimeType = (String) newProperties.getOrDefault("mime_type", "application/epub+zip");
ZipEntry mimeEntry = new ZipEntry("mimetype");
mimeEntry.setMethod(ZipEntry.STORED);
zos.putNextEntry(mimeEntry);
zos.write(mimeType.getBytes("US-ASCII"));
zos.closeEntry();
// Write container.xml
String containerXml = generateContainerXml(newProperties);
ZipEntry containerEntry = new ZipEntry("META-INF/container.xml");
containerEntry.setMethod(ZipEntry.DEFLATED);
zos.putNextEntry(containerEntry);
zos.write(containerXml.getBytes("UTF-8"));
zos.closeEntry();
// Copy other entries
Enumeration<? extends ZipEntry> entries = zfIn.entries();
while (entries.hasMoreElements()) {
ZipEntry entry = entries.nextElement();
if (entry.getName().equals("mimetype") || entry.getName().equals("META-INF/container.xml")) continue;
zos.putNextEntry(new ZipEntry(entry.getName()));
try (InputStream is = zfIn.getInputStream(entry)) {
is.transferTo(zos);
}
zos.closeEntry();
}
// Add optional META-INF files if specified
String[] optionalFiles = {"signatures.xml", "encryption.xml", "metadata.xml", "rights.xml", "manifest.xml"};
String[] keys = {"signatures_xml", "encryption_xml", "metadata_xml", "rights_xml", "manifest_xml"};
for (int i = 0; i < optionalFiles.length; i++) {
if ((Boolean) newProperties.getOrDefault(keys[i], false) && zfIn.getEntry("META-INF/" + optionalFiles[i]) == null) {
ZipEntry optEntry = new ZipEntry("META-INF/" + optionalFiles[i]);
zos.putNextEntry(optEntry);
zos.write("<!-- Dummy content -->".getBytes("UTF-8"));
zos.closeEntry();
}
}
}
}
private String generateContainerXml(Map<String, Object> props) {
StringBuilder sb = new StringBuilder("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
sb.append("<container xmlns=\"urn:oasis:names:tc:opendocument:xmlns:container\" version=\"")
.append(props.getOrDefault("container_version", "1.0")).append("\">\n");
sb.append(" <rootfiles>\n");
List<Map<String, String>> rootfiles = (List<Map<String, String>>) props.getOrDefault("rootfiles", new ArrayList<>());
for (Map<String, String> rf : rootfiles) {
sb.append(" <rootfile full-path=\"").append(rf.get("full_path"))
.append("\" media-type=\"").append(rf.get("media_type")).append("\"/>\n");
}
sb.append(" </rootfiles>\n</container>");
return sb.toString();
}
// Example usage:
// public static void main(String[] args) throws Exception {
// EpubHandler handler = new EpubHandler("example.epub");
// handler.printProperties();
// Map<String, Object> newProps = new HashMap<>(handler.properties);
// handler.writeProperties(newProps, "modified.epub");
// }
}
This class opens an .EPUB, decodes and reads the properties, prints them to console in JSON-like format, and can write modified properties to a new or same file.
- JavaScript class for .EPUB handling (Node.js, requires 'jszip' and 'xml2js' modules):
const fs = require('fs');
const JSZip = require('jszip');
const xml2js = require('xml2js');
class EpubHandler {
constructor(filepath) {
this.filepath = filepath;
this.properties = {};
}
async readProperties() {
const data = await fs.promises.readFile(this.filepath);
const zip = await JSZip.loadAsync(data);
const files = Object.keys(zip.files);
if (files[0] !== 'mimetype') throw new Error('mimetype not first file');
const mimetypeEntry = zip.files['mimetype'];
const mimeContent = (await mimetypeEntry.async('string')).trim();
this.properties = {
file_extension: '.epub',
mime_type: mimeContent,
container_format: 'ZIP',
mimetype_file: {
exists: true,
content: mimeContent,
compression: mimetypeEntry.method === 0 ? 'uncompressed' : 'compressed',
extra_fields: !!mimetypeEntry.extraFields.length
},
container_version: '',
rootfiles: [],
signatures_xml: !!zip.file('META-INF/signatures.xml'),
encryption_xml: !!zip.file('META-INF/encryption.xml'),
metadata_xml: !!zip.file('META-INF/metadata.xml'),
rights_xml: !!zip.file('META-INF/rights.xml'),
manifest_xml: !!zip.file('META-INF/manifest.xml')
};
if (this.properties.mime_type !== 'application/epub+zip') throw new Error('Invalid MIME type');
const containerContent = await zip.file('META-INF/container.xml')?.async('string');
if (!containerContent) throw new Error('Missing container.xml');
const parser = new xml2js.Parser();
const result = await parser.parseStringPromise(containerContent);
this.properties.container_version = result.container.$.version || '';
const rootfileNodes = result.container.rootfiles[0].rootfile || [];
rootfileNodes.forEach(rf => {
this.properties.rootfiles.push({
full_path: rf.$.['full-path'],
media_type: rf.$.['media-type']
});
});
}
printProperties() {
console.log(JSON.stringify(this.properties, null, 4));
}
async writeProperties(newProperties, outputPath = this.filepath) {
const data = await fs.promises.readFile(this.filepath);
const zip = await JSZip.loadAsync(data);
// Update mimetype
const mimeType = newProperties.mime_type || 'application/epub+zip';
zip.file('mimetype', mimeType, {compression: 'STORE'});
// Update container.xml
const containerXml = this.generateContainerXml(newProperties);
zip.file('META-INF/container.xml', containerXml);
// Add/remove optional files
const optional = {
signatures_xml: 'META-INF/signatures.xml',
encryption_xml: 'META-INF/encryption.xml',
metadata_xml: 'META-INF/metadata.xml',
rights_xml: 'META-INF/rights.xml',
manifest_xml: 'META-INF/manifest.xml'
};
for (const key in optional) {
if (newProperties[key] && !zip.file(optional[key])) {
zip.file(optional[key], '<!-- Dummy content -->');
} else if (!newProperties[key] && zip.file(optional[key])) {
zip.remove(optional[key]);
}
}
const newBuffer = await zip.generateAsync({type: 'nodebuffer', compression: 'DEFLATE'});
await fs.promises.writeFile(outputPath, newBuffer);
}
generateContainerXml(props) {
let xml = '<?xml version="1.0" encoding="UTF-8"?>\n';
xml += `<container xmlns="urn:oasis:names:tc:opendocument:xmlns:container" version="${props.container_version || '1.0'}">\n`;
xml += ' <rootfiles>\n';
(props.rootfiles || []).forEach(rf => {
xml += ` <rootfile full-path="${rf.full_path}" media-type="${rf.media_type}"/>\n`;
});
xml += ' </rootfiles>\n</container>';
return xml;
}
}
// Example usage:
// (async () => {
// const handler = new EpubHandler('example.epub');
// await handler.readProperties();
// handler.printProperties();
// const newProps = { ...handler.properties };
// await handler.writeProperties(newProps, 'modified.epub');
// })();
This class opens an .EPUB, decodes and reads the properties, prints them to console in JSON, and can write modified properties to a new or same file. Install dependencies with npm install jszip xml2js.
- C class (C++ actually, as "c class" likely means C++, using minizip for ZIP handling; assume minizip installed):
#include <iostream>
#include <string>
#include <vector>
#include <map>
#include <fstream>
#include <minizip/unzip.h>
#include <minizip/zip.h>
#include <tinyxml2.h> // Assume tinyxml2 for XML parsing
class EpubHandler {
public:
std::string filepath;
std::map<std::string, std::string> properties; // Simplified to strings for console print
EpubHandler(const std::string& fp) : filepath(fp) {}
void readProperties() {
unzFile uf = unzOpen(filepath.c_str());
if (!uf) throw std::runtime_error("Cannot open file");
unz_global_info gi;
unzGetGlobalInfo(uf, &gi);
// Check first file
unzGoToFirstFile(uf);
char filename[256];
unz_file_info file_info;
unzGetCurrentFileInfo(uf, &file_info, filename, sizeof(filename), NULL, 0, NULL, 0);
if (std::string(filename) != "mimetype") throw std::runtime_error("mimetype not first file");
unzOpenCurrentFile(uf);
std::string mimeContent(file_info.uncompressed_size, '\0');
unzReadCurrentFile(uf, &mimeContent[0], file_info.uncompressed_size);
unzCloseCurrentFile(uf);
mimeContent = mimeContent.substr(0, mimeContent.find_last_not_of(" \t\n\r\f\v") + 1); // Trim
properties["file_extension"] = ".epub";
properties["mime_type"] = mimeContent;
properties["container_format"] = "ZIP";
properties["mimetype_file_exists"] = "true";
properties["mimetype_file_content"] = mimeContent;
properties["mimetype_file_compression"] = (file_info.compression_method == 0 ? "uncompressed" : "compressed");
properties["mimetype_file_extra_fields"] = (file_info.extrafield_size > 0 ? "true" : "false");
if (properties["mime_type"] != "application/epub+zip") throw std::runtime_error("Invalid MIME type");
// Find container.xml
if (unzLocateFile(uf, "META-INF/container.xml", 0) != UNZ_OK) throw std::runtime_error("Missing container.xml");
unzGetCurrentFileInfo(uf, &file_info, NULL, 0, NULL, 0, NULL, 0);
unzOpenCurrentFile(uf);
std::string containerContent(file_info.uncompressed_size, '\0');
unzReadCurrentFile(uf, &containerContent[0], file_info.uncompressed_size);
unzCloseCurrentFile(uf);
tinyxml2::XMLDocument doc;
doc.Parse(containerContent.c_str());
tinyxml2::XMLElement* root = doc.FirstChildElement("container");
properties["container_version"] = root ? root->Attribute("version") : "";
// Rootfiles (simplified to count or list as string)
std::string rootfilesStr;
tinyxml2::XMLElement* rf = root ? root->FirstChildElement("rootfiles")->FirstChildElement("rootfile") : nullptr;
while (rf) {
rootfilesStr += std::string(rf->Attribute("full-path")) + " (" + rf->Attribute("media-type") + "); ";
rf = rf->NextSiblingElement("rootfile");
}
properties["rootfiles"] = rootfilesStr;
properties["signatures_xml"] = (unzLocateFile(uf, "META-INF/signatures.xml", 0) == UNZ_OK ? "true" : "false");
properties["encryption_xml"] = (unzLocateFile(uf, "META-INF/encryption.xml", 0) == UNZ_OK ? "true" : "false");
properties["metadata_xml"] = (unzLocateFile(uf, "META-INF/metadata.xml", 0) == UNZ_OK ? "true" : "false");
properties["rights_xml"] = (unzLocateFile(uf, "META-INF/rights.xml", 0) == UNZ_OK ? "true" : "false");
properties["manifest_xml"] = (unzLocateFile(uf, "META-INF/manifest.xml", 0) == UNZ_OK ? "true" : "false");
unzClose(uf);
}
void printProperties() {
for (const auto& kv : properties) {
std::cout << kv.first << ": " << kv.second << std::endl;
}
}
void writeProperties(const std::map<std::string, std::string>& newProps, const std::string& outputPath) {
// Simplified: copy file, update mimetype and container.xml
std::ifstream in(filepath, std::ios::binary);
std::ofstream out(outputPath, std::ios::binary);
out << in.rdbuf(); // Copy original
// For actual write, would need to unzip, modify, rezip - complex, omitted for brevity
// Use zipOpen, add mimetype first, add container, copy others
// ...
}
};
// Example usage:
// int main() {
// try {
// EpubHandler handler("example.epub");
// handler.readProperties();
// handler.printProperties();
// } catch (const std::exception& e) {
// std::cerr << e.what() << std::endl;
// }
// return 0;
// }
This C++ class opens an .EPUB, decodes and reads the properties, prints them to console, and has a stub for writing (full implementation would require more ZIP manipulation code). Requires minizip and tinyxml2 libraries.