Mirrors/Stirling-PDF
Mirrors/Stirling-PDF
1
0
Fork 0
mirror of https://github.com/Frooodle/Stirling-PDF.git synced 2026-02-01 20:10:35 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat(conversion): add PDF to EPUB/AZW3 conversion support and settings (#5434)

Browse Source 
# Description of Changes


This pull request introduces support for converting PDF files to eBook
formats (EPUB and AZW3) in the frontend. It adds new user interface
options for PDF-to-eBook conversion, updates the conversion logic and
parameters, and ensures the new formats are integrated into the
conversion matrix and endpoints. The most important changes are grouped
below:

**PDF to eBook (EPUB/AZW3) Conversion Support**

* Added a new `ConvertToEpubSettings` component that provides UI
controls for PDF-to-eBook options, including chapter detection, target
device selection, and output format.
(`frontend/src/core/components/tools/convert/ConvertToEpubSettings.tsx`)
* Updated `ConvertSettings` to render the new eBook options when
converting from PDF to EPUB or AZW3, and set default values for these
options.
(`frontend/src/core/components/tools/convert/ConvertSettings.tsx`)
* Extended the `ConvertParameters` interface and default parameters to
include `epubOptions` for the new settings.
(`frontend/src/core/hooks/tools/convert/useConvertParameters.ts`)

**Conversion Logic and API Integration**

* Updated the conversion endpoints, endpoint names, and conversion
matrix to support PDF-to-EPUB/AZW3 conversions.
(`frontend/src/core/constants/convertConstants.ts`)
* Modified the conversion operation logic to handle `epubOptions` and
ensure that PDF-to-eBook conversions process each file separately and
send the correct options to the backend.
(`frontend/src/core/hooks/tools/convert/useConvertOperation.ts`)
**Localization and Tool Registry Updates**

* Added localization strings for the new eBook conversion options.
(`frontend/public/locales/en-GB/translation.toml`)
* Registered the new PDF-to-eBook operation in the tool catalog and test
helpers. (`frontend/src/core/data/useTranslatedToolRegistry.tsx`,
`frontend/src/core/tests/helpers/conversionEndpointDiscovery.ts`)



<img width="364" height="995" alt="image"
src="https://github.com/user-attachments/assets/c54c50c0-1b86-4074-aef8-b038c6caeb49"
/>

<!--
Please provide a summary of the changes, including:

- What was changed
- Why the change was made
- Any challenges encountered

Closes #(issue_number)
-->

---

## Checklist

### General

- [X] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [X] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [X] I have performed a self-review of my own code
- [X] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### Translations (if applicable)

- [ ] I ran
[`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md)

### UI Changes (if applicable)

- [X] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [X] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.

Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
Co-authored-by: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>
This commit is contained in:
Balázs Szücs 2026-01-13 23:22:23 +01:00 committed by GitHub
parent e7b030e6b5
commit b00bd760c8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 188 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
frontend/public/locales/en-GB/translation.toml
View File

@ -1308,6 +1308,18 @@ includePageNumbersDesc = "Add page numbers to the generated PDF"
optimizeForEbookPdf = "Optimize for ebook readers"
optimizeForEbookPdfDesc = "Optimize the PDF for eBook reading (smaller file size, better rendering on eInk devices)"
[convert.epubOptions]
epubOptions = "PDF to eBook Options"
epubOptionsDesc = "Options for converting PDF to EPUB/AZW3"
detectChapters = "Detect chapters"
detectChaptersDesc = "Detect headings that look like chapters and insert EPUB page breaks"
targetDevice = "Target device"
targetDeviceDesc = "Choose an output profile optimized for the reader device"
outputFormat = "Output format"
outputFormatDesc = "Choose the output format for the ebook"
tabletPhone = "Tablet/Phone (with images)"
kindleEink = "Kindle e-Ink (text optimized)"
[imageToPdf]
tags = "conversion,img,jpg,picture,photo"

18
frontend/src/core/components/tools/convert/ConvertSettings.tsx
View File

@ -20,6 +20,7 @@ import ConvertToPdfaSettings from "@app/components/tools/convert/ConvertToPdfaSe
import ConvertFromCbrSettings from "@app/components/tools/convert/ConvertFromCbrSettings";
import ConvertToCbrSettings from "@app/components/tools/convert/ConvertToCbrSettings";
import ConvertFromEbookSettings from "@app/components/tools/convert/ConvertFromEbookSettings";
import ConvertToEpubSettings from "@app/components/tools/convert/ConvertToEpubSettings";
import { ConvertParameters } from "@app/hooks/tools/convert/useConvertParameters";
import {
FROM_FORMAT_OPTIONS,
@ -163,6 +164,11 @@ const ConvertSettings = ({
includePageNumbers: false,
optimizeForEbook: false,
});
onParameterChange('epubOptions', {
detectChapters: true,
targetDevice: 'TABLET_PHONE_IMAGES',
outputFormat: 'EPUB',
});
onParameterChange('isSmartDetection', false);
onParameterChange('smartDetectionType', 'none');
};
@ -423,6 +429,18 @@ const ConvertSettings = ({
</>
)}
{/* PDF to EPUB/AZW3 options */}
{parameters.fromExtension === 'pdf' && ['epub', 'azw3'].includes(parameters.toExtension) && (
<>
<Divider />
<ConvertToEpubSettings
parameters={parameters}
onParameterChange={onParameterChange}
disabled={disabled}
/>
</>
)}
</Stack>
);
};

103
frontend/src/core/components/tools/convert/ConvertToEpubSettings.tsx Normal file
View File

@ -0,0 +1,103 @@
import { Stack, Select, Checkbox } from "@mantine/core";
import { useTranslation } from "react-i18next";
import { ConvertParameters } from "@app/hooks/tools/convert/useConvertParameters";
interface ConvertToEpubSettingsProps {
parameters: ConvertParameters;
onParameterChange: <K extends keyof ConvertParameters>(key: K, value: ConvertParameters[K]) => void;
disabled?: boolean;
}
const ConvertToEpubSettings = ({
parameters,
onParameterChange,
disabled = false
}: ConvertToEpubSettingsProps) => {
const { t } = useTranslation();
const handleDetectChaptersChange = (value: boolean) => {
onParameterChange('epubOptions', {
detectChapters: value,
targetDevice: parameters.epubOptions?.targetDevice ?? 'TABLET_PHONE_IMAGES',
outputFormat: parameters.epubOptions?.outputFormat ?? parameters.toExtension === 'azw3' ? 'AZW3' : 'EPUB',
});
};
const handleTargetDeviceChange = (value: string | null) => {
if (value) {
onParameterChange('epubOptions', {
detectChapters: parameters.epubOptions?.detectChapters ?? true,
targetDevice: value,
outputFormat: parameters.epubOptions?.outputFormat ?? parameters.toExtension === 'azw3' ? 'AZW3' : 'EPUB',
});
}
};
const handleOutputFormatChange = (value: string | null) => {
if (value) {
onParameterChange('epubOptions', {
detectChapters: parameters.epubOptions?.detectChapters ?? true,
targetDevice: parameters.epubOptions?.targetDevice ?? 'TABLET_PHONE_IMAGES',
outputFormat: value,
});
}
};
// Initialize epubOptions if not present, set output format based on toExtension
const epubOptions = parameters.epubOptions || {
detectChapters: true,
targetDevice: 'TABLET_PHONE_IMAGES',
outputFormat: parameters.toExtension === 'azw3' ? 'AZW3' : 'EPUB',
};
// Sync output format with selected target extension if not manually set
if (parameters.toExtension === 'azw3' && epubOptions.outputFormat !== 'AZW3') {
handleOutputFormatChange('AZW3');
} else if (parameters.toExtension === 'epub' && epubOptions.outputFormat !== 'EPUB') {
handleOutputFormatChange('EPUB');
}
return (
<Stack gap="sm" data-testid="epub-settings">
<Checkbox
label={t("convert.epubOptions.detectChapters", "Detect chapters")}
description={t("convert.epubOptions.detectChaptersDesc", "Detect headings that look like chapters and insert EPUB page breaks")}
checked={epubOptions.detectChapters}
onChange={(event) => handleDetectChaptersChange(event.currentTarget.checked)}
disabled={disabled}
/>
<Select
label={t("convert.epubOptions.targetDevice", "Target device")}
description={t("convert.epubOptions.targetDeviceDesc", "Choose an output profile optimized for the reader device")}
value={epubOptions.targetDevice}
onChange={handleTargetDeviceChange}
disabled={disabled}
data={[
{
value: 'TABLET_PHONE_IMAGES',
label: t("convert.epubOptions.tabletPhone", "Tablet/Phone (with images)")
},
{
value: 'KINDLE_EINK_TEXT',
label: t("convert.epubOptions.kindleEink", "Kindle e-Ink (text optimized)")
}
]}
/>
<Select
label={t("convert.epubOptions.outputFormat", "Output format")}
description={t("convert.epubOptions.outputFormatDesc", "Choose the output format for the ebook")}
value={epubOptions.outputFormat}
onChange={handleOutputFormatChange}
disabled={disabled}
data={[
{ value: 'EPUB', label: 'EPUB' },
{ value: 'AZW3', label: 'AZW3' }
]}
/>
</Stack>
);
};
export default ConvertToEpubSettings;

9
frontend/src/core/constants/convertConstants.ts
View File

@ -37,6 +37,7 @@ export const CONVERSION_ENDPOINTS = {
'cbr-pdf': '/api/v1/convert/cbr/pdf',
'pdf-cbr': '/api/v1/convert/pdf/cbr',
'ebook-pdf': '/api/v1/convert/ebook/pdf',
'pdf-epub': '/api/v1/convert/pdf/epub',
'pdf-text-editor': '/api/v1/convert/pdf/text-editor',
'text-editor-pdf': '/api/v1/convert/text-editor/pdf'
} as const;
@ -61,6 +62,7 @@ export const ENDPOINT_NAMES = {
'ebook-pdf': 'ebook-to-pdf',
'cbr-pdf': 'cbr-to-pdf',
'pdf-cbr': 'pdf-to-cbr',
'pdf-epub': 'pdf-to-epub',
'pdf-text-editor': 'pdf-to-text-editor',
'text-editor-pdf': 'text-editor-to-pdf'
} as const;
@ -124,13 +126,15 @@ export const TO_FORMAT_OPTIONS = [
{ value: 'webp', label: 'WEBP', group: 'Image' },
{ value: 'html', label: 'HTML', group: 'Web' },
{ value: 'xml', label: 'XML', group: 'Web' },
{ value: 'epub', label: 'EPUB', group: 'eBook' },
{ value: 'azw3', label: 'AZW3', group: 'eBook' },
];
// Conversion matrix - what each source format can convert to
export const CONVERSION_MATRIX: Record<string, string[]> = {
'any': ['pdf'], // Mixed files always convert to PDF
'image': ['pdf'], // Multiple images always convert to PDF
'pdf': ['png', 'jpg', 'gif', 'tiff', 'bmp', 'webp', 'docx', 'odt', 'pptx', 'odp', 'csv', 'txt', 'rtf', 'md', 'html', 'xml', 'pdfa', 'cbz', 'cbr'],
'pdf': ['png', 'jpg', 'gif', 'tiff', 'bmp', 'webp', 'docx', 'odt', 'pptx', 'odp', 'csv', 'txt', 'rtf', 'md', 'html', 'xml', 'pdfa', 'cbz', 'cbr', 'epub', 'azw3'],
'cbz': ['pdf'],
'docx': ['pdf'], 'doc': ['pdf'], 'odt': ['pdf'],
'xlsx': ['pdf'], 'xls': ['pdf'], 'ods': ['pdf'],
@ -159,7 +163,8 @@ export const EXTENSION_TO_ENDPOINT: Record<string, Record<string, string>> = {
'html': 'pdf-to-html', 'xml': 'pdf-to-xml',
'pdfa': 'pdf-to-pdfa',
'cbr': 'pdf-to-cbr',
'cbz': 'pdf-to-cbz'
'cbz': 'pdf-to-cbz',
'epub': 'pdf-to-epub', 'azw3': 'pdf-to-epub'
},
'cbz': { 'pdf': 'cbz-to-pdf' },
'docx': { 'pdf': 'file-to-pdf' }, 'doc': { 'pdf': 'file-to-pdf' }, 'odt': { 'pdf': 'file-to-pdf' },

1
frontend/src/core/data/useTranslatedToolRegistry.tsx
View File

@ -892,6 +892,7 @@ export function useTranslatedToolCatalog(): TranslatedToolCatalog {
"pdf-to-markdown",
"pdf-to-pdfa",
"eml-to-pdf",
"pdf-to-epub",
],
operationConfig: convertOperationConfig,

8
frontend/src/core/hooks/tools/convert/useConvertOperation.ts
View File

@ -23,6 +23,8 @@ export const shouldProcessFilesSeparately = (
(parameters.fromExtension === 'pdf' && ['txt', 'rtf', 'csv'].includes(parameters.toExtension)) ||
// PDF to CBR conversions (each PDF should generate its own archive)
(parameters.fromExtension === 'pdf' && parameters.toExtension === 'cbr') ||
// PDF to EPUB/AZW3 conversions (each PDF should generate its own ebook)
(parameters.fromExtension === 'pdf' && ['epub', 'azw3'].includes(parameters.toExtension)) ||
// PDF to office format conversions (each PDF should generate its own office file)
(parameters.fromExtension === 'pdf' && isOfficeFormat(parameters.toExtension)) ||
// Office files to PDF conversions (each file should be processed separately via LibreOffice)
@ -42,7 +44,7 @@ export const shouldProcessFilesSeparately = (
// Static function that can be used by both the hook and automation executor
export const buildConvertFormData = (parameters: ConvertParameters, selectedFiles: File[]): FormData => {
const formData = new FormData();
const { fromExtension, toExtension, imageOptions, htmlOptions, emailOptions, pdfaOptions, cbrOptions, pdfToCbrOptions, cbzOptions, cbzOutputOptions, ebookOptions } = parameters;
const { fromExtension, toExtension, imageOptions, htmlOptions, emailOptions, pdfaOptions, cbrOptions, pdfToCbrOptions, cbzOptions, cbzOutputOptions, ebookOptions, epubOptions } = parameters;
selectedFiles.forEach(file => {
formData.append("fileInput", file);
@ -88,6 +90,10 @@ export const buildConvertFormData = (parameters: ConvertParameters, selectedFile
formData.append("includeTableOfContents", (ebookOptions?.includeTableOfContents ?? false).toString());
formData.append("includePageNumbers", (ebookOptions?.includePageNumbers ?? false).toString());
formData.append("optimizeForEbook", (ebookOptions?.optimizeForEbook ?? false).toString());
} else if (fromExtension === 'pdf' && ['epub', 'azw3'].includes(toExtension)) {
formData.append("detectChapters", (epubOptions?.detectChapters ?? true).toString());
formData.append("targetDevice", epubOptions?.targetDevice ?? 'TABLET_PHONE_IMAGES');
formData.append("outputFormat", epubOptions?.outputFormat ?? (toExtension === 'azw3' ? 'AZW3' : 'EPUB'));
}
return formData;

10
frontend/src/core/hooks/tools/convert/useConvertParameters.ts
View File

@ -54,6 +54,11 @@ export interface ConvertParameters extends BaseParameters {
includePageNumbers: boolean;
optimizeForEbook: boolean;
};
epubOptions?: {
detectChapters: boolean;
targetDevice: string;
outputFormat: string;
};
isSmartDetection: boolean;
smartDetectionType: 'mixed' | 'images' | 'web' | 'none';
}
@ -105,6 +110,11 @@ export const defaultParameters: ConvertParameters = {
includePageNumbers: false,
optimizeForEbook: false,
},
epubOptions: {
detectChapters: true,
targetDevice: 'TABLET_PHONE_IMAGES',
outputFormat: 'EPUB',
},
isSmartDetection: false,
smartDetectionType: 'none',
};

53
frontend/src/core/tests/helpers/conversionEndpointDiscovery.ts
View File

@ -1,6 +1,6 @@
/**
* Conversion Endpoint Discovery for E2E Testing
*
*
* Uses the backend's endpoint configuration API to discover available conversions
*/
@ -121,6 +121,13 @@ const ALL_CONVERSION_ENDPOINTS: ConversionEndpoint[] = [
description: 'Convert email (EML) to PDF',
apiPath: '/api/v1/convert/eml/pdf'
},
{
endpoint: 'pdf-to-epub',
fromFormat: 'pdf',
toFormat: 'epub',
description: 'Convert PDF to EPUB/AZW3',
apiPath: '/api/v1/convert/pdf/epub'
},
{
endpoint: 'eml-to-pdf', // MSG uses same endpoint as EML
fromFormat: 'msg',
@ -145,8 +152,8 @@ export class ConversionEndpointDiscovery {
*/
async getAvailableConversions(): Promise<ConversionEndpoint[]> {
const endpointStatuses = await this.getEndpointStatuses();
return ALL_CONVERSION_ENDPOINTS.filter(conversion =>
return ALL_CONVERSION_ENDPOINTS.filter(conversion =>
endpointStatuses.get(conversion.endpoint) === true
);
}
@ -156,8 +163,8 @@ export class ConversionEndpointDiscovery {
*/
async getUnavailableConversions(): Promise<ConversionEndpoint[]> {
const endpointStatuses = await this.getEndpointStatuses();
return ALL_CONVERSION_ENDPOINTS.filter(conversion =>
return ALL_CONVERSION_ENDPOINTS.filter(conversion =>
endpointStatuses.get(conversion.endpoint) === false
);
}
@ -175,16 +182,16 @@ export class ConversionEndpointDiscovery {
*/
async getConversionsByFormat(): Promise<Record<string, ConversionEndpoint[]>> {
const availableConversions = await this.getAvailableConversions();
const grouped: Record<string, ConversionEndpoint[]> = {};
availableConversions.forEach(conversion => {
if (!grouped[conversion.fromFormat]) {
grouped[conversion.fromFormat] = [];
}
grouped[conversion.fromFormat].push(conversion);
});
return grouped;
}
@ -193,7 +200,7 @@ export class ConversionEndpointDiscovery {
*/
async getSupportedTargetFormats(fromFormat: string): Promise<string[]> {
const availableConversions = await this.getAvailableConversions();
return availableConversions
.filter(conversion => conversion.fromFormat === fromFormat)
.map(conversion => conversion.toFormat);
@ -204,11 +211,11 @@ export class ConversionEndpointDiscovery {
*/
async getSupportedSourceFormats(): Promise<string[]> {
const availableConversions = await this.getAvailableConversions();
const sourceFormats = new Set(
availableConversions.map(conversion => conversion.fromFormat)
);
return Array.from(sourceFormats);
}
@ -224,33 +231,33 @@ export class ConversionEndpointDiscovery {
try {
const endpointNames = ALL_CONVERSION_ENDPOINTS.map(conv => conv.endpoint);
const endpointsParam = endpointNames.join(',');
const response = await fetch(
`${this.baseUrl}/api/v1/config/endpoints-enabled?endpoints=${encodeURIComponent(endpointsParam)}`
);
if (!response.ok) {
throw new Error(`Failed to fetch endpoint statuses: ${response.status} ${response.statusText}`);
}
const statusMap: Record<string, boolean> = await response.json();
// Convert to Map and cache
this.cache = new Map(Object.entries(statusMap));
this.cacheExpiry = Date.now() + this.CACHE_DURATION;
console.log(`Retrieved status for ${Object.keys(statusMap).length} conversion endpoints`);
return this.cache;
} catch (error) {
console.error('Failed to get endpoint statuses:', error);
// Fallback: assume all endpoints are disabled
const fallbackMap = new Map<string, boolean>();
ALL_CONVERSION_ENDPOINTS.forEach(conv => {
fallbackMap.set(conv.endpoint, false);
});
return fallbackMap;
}
}
@ -289,15 +296,15 @@ export const conversionDiscovery = new ConversionEndpointDiscovery();
export function useConversionEndpoints() {
const endpointNames = ALL_CONVERSION_ENDPOINTS.map(conv => conv.endpoint);
const { endpointStatus, loading, error, refetch } = useMultipleEndpointsEnabled(endpointNames);
const availableConversions = ALL_CONVERSION_ENDPOINTS.filter(
conv => endpointStatus[conv.endpoint] === true
);
const unavailableConversions = ALL_CONVERSION_ENDPOINTS.filter(
conv => endpointStatus[conv.endpoint] === false
);
return {
availableConversions,
unavailableConversions,
@ -308,4 +315,4 @@ export function useConversionEndpoints() {
refetch,
isConversionAvailable: (endpoint: string) => endpointStatus[endpoint] === true
};
}
}