0
# Worker API
1

2
The Worker API is the primary interface for OCR operations in Tesseract.js. Workers provide full lifecycle management for OCR tasks including text recognition, parameter configuration, filesystem operations, and resource cleanup.
3

4
## Capabilities
5

6
### Worker Creation
7

8
Creates a new OCR worker with language support and configuration options.
9

10
```javascript { .api }
11
/**
12
 * Creates a new OCR worker with specified languages and options
13
 * @param langs - Language code(s) for OCR recognition (default: 'eng')
14
 * @param oem - OCR Engine Mode (default: OEM.LSTM_ONLY)
15
 * @param options - Worker configuration options
16
 * @param config - Tesseract initialization configuration
17
 * @returns Promise resolving to Worker instance
18
 */
19
function createWorker(
20
  langs?: string | string[] | Lang[], 
21
  oem?: OEM, 
22
  options?: Partial<WorkerOptions>, 
23
  config?: string | Partial<InitOptions>
24
): Promise<Worker>;
25

26
interface Lang {
27
  code: string;
28
  data: unknown;
29
}
30
```
31

32
**Usage Examples:**
33

34
```javascript
35
import { createWorker, OEM } from 'tesseract.js';
36

37
// Basic worker with English
38
const worker = await createWorker('eng');
39

40
// Multi-language worker
41
const multiWorker = await createWorker(['eng', 'fra', 'deu']);
42

43
// Worker with custom options
44
const customWorker = await createWorker('eng', OEM.LSTM_ONLY, {
45
  logger: m => console.log(m),
46
  errorHandler: err => console.error(err)
47
});
48
```
49

50
### Text Recognition
51

52
Recognizes text from images with comprehensive output format options.
53

54
```javascript { .api }
55
/**
56
 * Recognizes text from an image
57
 * @param image - Image input in various supported formats
58
 * @param options - Recognition options including region of interest
59
 * @param output - Output format configuration
60
 * @param jobId - Optional job identifier for tracking
61
 * @returns Promise resolving to recognition results
62
 */
63
recognize(
64
  image: ImageLike, 
65
  options?: Partial<RecognizeOptions>, 
66
  output?: Partial<OutputFormats>, 
67
  jobId?: string
68
): Promise<RecognizeResult>;
69

70
interface RecognizeOptions {
71
  rectangle: Rectangle;
72
  pdfTitle: string;
73
  pdfTextOnly: boolean;
74
  rotateAuto: boolean;
75
  rotateRadians: number;
76
}
77

78
interface Rectangle {
79
  left: number;
80
  top: number;
81
  width: number;
82
  height: number;
83
}
84

85
interface OutputFormats {
86
  text: boolean;
87
  blocks: boolean;
88
  layoutBlocks: boolean;
89
  hocr: boolean;
90
  tsv: boolean;
91
  box: boolean;
92
  unlv: boolean;
93
  osd: boolean;
94
  pdf: boolean;
95
  imageColor: boolean;
96
  imageGrey: boolean;
97
  imageBinary: boolean;
98
  debug: boolean;
99
}
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
// Basic text recognition
106
const { data: { text } } = await worker.recognize('image.png');
107

108
// Recognition with region of interest
109
const result = await worker.recognize('image.png', {
110
  rectangle: { left: 100, top: 50, width: 300, height: 200 }
111
});
112

113
// Multiple output formats
114
const fullResult = await worker.recognize('image.png', {}, {
115
  text: true,
116
  hocr: true,
117
  pdf: true
118
});
119
```
120

121
### Orientation and Script Detection
122

123
Detects text orientation and script from images.
124

125
```javascript { .api }
126
/**
127
 * Detects orientation and script information from image
128
 * @param image - Image input in various supported formats
129
 * @param jobId - Optional job identifier for tracking
130
 * @returns Promise resolving to detection results
131
 */
132
detect(image: ImageLike, jobId?: string): Promise<DetectResult>;
133

134
interface DetectResult {
135
  jobId: string;
136
  data: DetectData;
137
}
138

139
interface DetectData {
140
  tesseract_script_id: number | null;
141
  script: string | null;
142
  script_confidence: number | null;
143
  orientation_degrees: number | null;
144
  orientation_confidence: number | null;
145
}
146
```
147

148
**Usage Examples:**
149

150
```javascript
151
const detection = await worker.detect('rotated-image.png');
152
console.log(detection.data.orientation_degrees); // e.g., 90
153
console.log(detection.data.script); // e.g., 'Latin'
154
```
155

156
### Parameter Configuration
157

158
Sets Tesseract-specific parameters for fine-tuning OCR behavior.
159

160
```javascript { .api }
161
/**
162
 * Sets OCR parameters for the worker
163
 * @param params - Parameter key-value pairs
164
 * @param jobId - Optional job identifier
165
 * @returns Promise resolving to configuration result
166
 */
167
setParameters(params: Partial<WorkerParams>, jobId?: string): Promise<ConfigResult>;
168

169
interface WorkerParams {
170
  tessedit_pageseg_mode: PSM;
171
  tessedit_char_whitelist: string;
172
  tessedit_char_blacklist: string;
173
  preserve_interword_spaces: string;
174
  user_defined_dpi: string;
175
  [propName: string]: any;
176
}
177
```
178

179
**Usage Examples:**
180

181
```javascript
182
// Restrict to numbers only
183
await worker.setParameters({
184
  tessedit_char_whitelist: '0123456789'
185
});
186

187
// Set page segmentation mode
188
await worker.setParameters({
189
  tessedit_pageseg_mode: PSM.SINGLE_LINE
190
});
191

192
// Preserve spaces between words
193
await worker.setParameters({
194
  preserve_interword_spaces: '1'
195
});
196
```
197

198
### Worker Reinitialization
199

200
Reinitializes worker with new languages or engine settings.
201

202
```javascript { .api }
203
/**
204
 * Reinitializes worker with new languages or configuration
205
 * @param langs - New language code(s)
206
 * @param oem - New OCR Engine Mode
207
 * @param config - New initialization configuration
208
 * @param jobId - Optional job identifier
209
 * @returns Promise resolving to configuration result
210
 */
211
reinitialize(
212
  langs?: string | Lang[], 
213
  oem?: OEM, 
214
  config?: string | Partial<InitOptions>, 
215
  jobId?: string
216
): Promise<ConfigResult>;
217

218
interface InitOptions {
219
  load_system_dawg: string;
220
  load_freq_dawg: string;
221
  load_unambig_dawg: string;
222
  load_punc_dawg: string;
223
  load_number_dawg: string;
224
  load_bigram_dawg: string;
225
}
226
```
227

228
**Usage Examples:**
229

230
```javascript
231
// Switch to different language
232
await worker.reinitialize('fra');
233

234
// Switch to multiple languages
235
await worker.reinitialize(['eng', 'chi_sim']);
236

237
// Change engine mode
238
await worker.reinitialize('eng', OEM.TESSERACT_ONLY);
239
```
240

241
### Filesystem Operations
242

243
Direct access to worker's internal filesystem for advanced use cases.
244

245
```javascript { .api }
246
/**
247
 * Writes text to worker filesystem
248
 * @param path - File path
249
 * @param text - Text content to write
250
 * @param jobId - Optional job identifier
251
 * @returns Promise resolving to operation result
252
 */
253
writeText(path: string, text: string, jobId?: string): Promise<ConfigResult>;
254

255
/**
256
 * Reads text from worker filesystem
257
 * @param path - File path to read
258
 * @param jobId - Optional job identifier
259
 * @returns Promise resolving to file content
260
 */
261
readText(path: string, jobId?: string): Promise<ConfigResult>;
262

263
/**
264
 * Removes file from worker filesystem
265
 * @param path - File path to remove
266
 * @param jobId - Optional job identifier
267
 * @returns Promise resolving to operation result
268
 */
269
removeFile(path: string, jobId?: string): Promise<ConfigResult>;
270

271
/**
272
 * Direct filesystem method access
273
 * @param method - Filesystem method name
274
 * @param args - Method arguments
275
 * @param jobId - Optional job identifier
276
 * @returns Promise resolving to method result
277
 */
278
FS(method: string, args: any[], jobId?: string): Promise<ConfigResult>;
279
```
280

281
### Worker Loading (Deprecated)
282

283
The `load` method is deprecated and should be removed from code as workers now come pre-loaded.
284

285
```javascript { .api }
286
/**
287
 * @deprecated Workers now come pre-loaded, this method is deprecated and should be removed
288
 * @param jobId - Optional job identifier
289
 * @returns Promise resolving to configuration result
290
 */
291
load(jobId?: string): Promise<ConfigResult>;
292
```
293

294
### Worker Termination
295

296
Terminates worker and releases resources.
297

298
```javascript { .api }
299
/**
300
 * Terminates worker and releases resources
301
 * @param jobId - Optional job identifier
302
 * @returns Promise resolving when termination is complete
303
 */
304
terminate(jobId?: string): Promise<ConfigResult>;
305
```
306

307
**Usage Examples:**
308

309
```javascript
310
// Always terminate workers when done
311
await worker.terminate();
312

313
// In finally block to ensure cleanup
314
try {
315
  const result = await worker.recognize('image.png');
316
  // Process result
317
} finally {
318
  await worker.terminate();
319
}
320

321
// Using filesystem operations
322
await worker.writeText('/tmp/config.txt', 'custom config');
323
const config = await worker.readText('/tmp/config.txt');
324
await worker.removeFile('/tmp/config.txt');
325
```
326

327
## Result Types
328

329
```javascript { .api }
330
interface RecognizeResult {
331
  jobId: string;
332
  data: Page;
333
}
334

335
interface ConfigResult {
336
  jobId: string;
337
  data: any;
338
}
339

340
interface Page {
341
  blocks: Block[] | null;
342
  confidence: number;
343
  oem: string;
344
  osd: string;
345
  psm: string;
346
  text: string;
347
  version: string;
348
  hocr: string | null;
349
  tsv: string | null;
350
  box: string | null;
351
  unlv: string | null;
352
  sd: string | null;
353
  imageColor: string | null;
354
  imageGrey: string | null;
355
  imageBinary: string | null;
356
  rotateRadians: number | null;
357
  pdf: number[] | null;
358
  debug: string | null;
359
}
360

361
interface Block {
362
  paragraphs: Paragraph[];
363
  text: string;
364
  confidence: number;
365
  bbox: Bbox;
366
  blocktype: string;
367
  page: Page;
368
}
369

370
interface Paragraph {
371
  lines: Line[];
372
  text: string;
373
  confidence: number;
374
  bbox: Bbox;
375
  is_ltr: boolean;
376
}
377

378
interface Line {
379
  words: Word[];
380
  text: string;
381
  confidence: number;
382
  baseline: Baseline;
383
  rowAttributes: RowAttributes;
384
  bbox: Bbox;
385
}
386

387
interface Word {
388
  symbols: Symbol[];
389
  choices: Choice[];
390
  text: string;
391
  confidence: number;
392
  bbox: Bbox;
393
  font_name: string;
394
}
395

396
interface Symbol {
397
  text: string;
398
  confidence: number;
399
  bbox: Bbox;
400
  is_superscript: boolean;
401
  is_subscript: boolean;
402
  is_dropcap: boolean;
403
}
404

405
interface Choice {
406
  text: string;
407
  confidence: number;
408
}
409

410
interface Bbox {
411
  x0: number;
412
  y0: number;
413
  x1: number;
414
  y1: number;
415
}
416

417
interface Baseline {
418
  x0: number;
419
  y0: number;
420
  x1: number;
421
  y1: number;
422
  has_baseline: boolean;
423
}
424

425
interface RowAttributes {
426
  ascenders: number;
427
  descenders: number;
428
  row_height: number;
429
}
430
```
431

432
## Configuration Types
433

434
```javascript { .api }
435
interface WorkerOptions {
436
  corePath: string;
437
  langPath: string;
438
  cachePath: string;
439
  dataPath: string;
440
  workerPath: string;
441
  cacheMethod: string;
442
  workerBlobURL: boolean;
443
  gzip: boolean;
444
  legacyLang: boolean;
445
  legacyCore: boolean;
446
  logger: (arg: LoggerMessage) => void;
447
  errorHandler: (arg: any) => void;
448
}
449

450
interface LoggerMessage {
451
  jobId: string;
452
  progress: number;
453
  status: string;
454
  userJobId: string;
455
  workerId: string;
456
}
457
```