> For the complete documentation index, see [llms.txt](https://docs.calibratedsoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.calibratedsoftware.com/tin-man/tin-man-server.md).

# Tin Man Server

### Command Structure

```bash
tinman-server [general-options] <inputs> <command> [command-options]
```

**Note:** Press `Ctrl+C` to cancel any running operation.

### General Options

These options must come **before** your input files:

| Option               | Description                                                    |
| -------------------- | -------------------------------------------------------------- |
| `--threads N`        | Number of concurrent threads (1-5, default: 1)                 |
| `--progress=no-json` | Output progress as human-readable text instead of JSON         |
| `--no-recursive`     | Don't scan subfolders (default: recursive)                     |
| `--gpu-cuda`         | Use CUDA instead of OpenCL (Windows/NVIDIA only)               |
| `--gpu-encode`       | Enable GPU hardware encoding (default: CPU)                    |
| `--rawLog`           | Set all RAW files to Log                                       |
| `--raw709`           | Set all RAW files to Rec. 709                                  |
| `--raw709tonemap`    | Set all RAW files to Rec. 709 with tone mapping when available |
| `--raw2020`          | Set all RAW files to Rec. 2020                                 |
| `--rawHLG`           | Set all RAW files to Rec. 2020/HLG                             |
| `--rawPQ`            | Set all RAW files to Rec. 2020/PQ                              |
| `--rawACES`          | Set all RAW files to ACES AP0                                  |
| `--help`             | Show help message                                              |
| `--version`          | Show version information                                       |

### Input Methods

| Method         | Example                                              | Description                                                  |
| -------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| Single file    | `tinman-server /path/file.R3D ...`                   | Process one file                                             |
| Multiple files | `tinman-server /path/file1.R3D /path/file2.braw ...` | Process multiple files                                       |
| Folder         | `tinman-server /path/footage/ ...`                   | Process all supported files in folder (recursive by default) |
| File list      | `tinman-server @filelist.txt ...`                    | Text file containing list of files/folders to process        |

### Commands

#### generate-config

Generate a default configuration file that can be customized and reused for report configs or metadata burn-in on export configs.

**Options:**

| Option          | Description                                      |
| --------------- | ------------------------------------------------ |
| `--type TYPE`   | Config type: report, burnIn-MD (default: report) |
| `--output FILE` | Output config file path (required)               |
| `--stdout-json` | Output config JSON to stdout                     |

**Example:**

```bash
tinman-server generate-config --output my-config.json
```

***

#### metadata

Extract metadata from media files and generate reports in multiple formats.

**Options:**

| Option                | Description                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `--config FILE`       | Filepath to JSON file for report options                                                       |
| `--config-json JSON`  | Inline JSON string for report options                                                          |
| `--stdout-json`       | Output JSON report to stdout instead of file                                                   |
| `--summary`           | Summary mode: minimal JSON output (fileName, size, codec, resolution, fps, duration, timecode) |
| `--output-dir DIR`    | Output directory for report files                                                              |
| `--name REPORTNAME`   | Name to use for the report                                                                     |
| `--type TYPE`         | Report type: clips, contactsheet (default: clips). Multiple types can be specified             |
| `--format FORMAT`     | Output format: json, pdf, html, csv, xlsx (default: pdf). Multiple formats can be specified    |
| `--html-asset-folder` | Save HTML thumbnails as separate JPEG files (creates folder)                                   |
| `--rec709`            | Convert PDF thumbnails to Rec. 709 colorspace                                                  |
| `--rec709tonemap`     | Convert PDF thumbnails to Rec. 709 colorspace with tone mapping when needed                    |
| `--header.KEY VALUE`  | Override report header fields (see below)                                                      |

**Header override fields** (used with `--header.KEY VALUE`):

* `line1`, `line2`, `line3`, `line4`
* `comments`
* `logoLightMode_path`, `logoDarkMode_path`
* `logo_alignment` (left, center, right)

**Examples:**

```bash
# PDF report (default)
tinman-server /path/footage/ metadata --output-dir /path/reports/

# CSV report
tinman-server /path/footage/ metadata --output-dir /path/reports/ --format csv

# Multiple formats at once
tinman-server /path/footage/ metadata --output-dir /path/reports/ --format csv pdf xlsx

# Contact sheet report
tinman-server /path/footage/ metadata --output-dir /path/reports/ --type contactsheet --format pdf

# Both clips and contact sheet reports
tinman-server /path/footage/ metadata --output-dir /path/reports/ --type clips contactsheet --format pdf

# HTML report with separate JPEG sidecar assets
tinman-server /path/footage/ metadata --output-dir /path/reports/ --format html --html-asset-folder

# Summary mode to stdout (minimal JSON, no file written)
tinman-server /path/footage/ metadata --summary --stdout-json

# Inline JSON config
tinman-server /path/footage/ metadata --config-json "{...}" --output-dir /path/reports/

# Using custom config file
tinman-server /path/footage/ metadata --config my-config.json --output-dir /path/reports/

# Override report header fields
tinman-server /path/footage/ metadata --output-dir /path/reports/ \
  --header.line1 "Production Title" --header.line2 "Day 1" \
  --header.logo_alignment center

# With threading
tinman-server --threads 3 /path/footage/ metadata --output-dir /path/reports/ --format csv
```

***

#### export

Export and transcode media files using system presets or custom preset files.

**Options:**

| Option                         | Description                                                                                     |
| ------------------------------ | ----------------------------------------------------------------------------------------------- |
| `--list-presets`               | List all available system export presets                                                        |
| `--preset FILE`                | Export preset (system preset name or path to custom JSON file)                                  |
| `--resolution RES`             | Preset override resolution: half, quarter, eighth                                               |
| `--max-width N`                | Preset override resolution: scale to max width, height auto-calculated                          |
| `--fixed-size W H`             | Preset override resolution: exact output width and height                                       |
| `--bitrate T M`                | Preset override bitrate: target and max bitrate in kbps, 100 to 400000 (H.264/H.265 only)       |
| `--src-resize`                 | Use source resizing when possible                                                               |
| `--burnIn-TC`                  | Burn in TimeCode                                                                                |
| `--burnIn-MD`                  | Burn in Metadata (uses conservative defaults)                                                   |
| `--burnIn-MD-config FILE`      | JSON config for per-field MD burn-in toggles                                                    |
| `--burnIn-MD-config-json JSON` | Inline JSON for per-field MD burn-in toggles                                                    |
| `--rec709`                     | Preset override output colorspace: convert to Rec. 709 colorspace                               |
| `--rec709tonemap`              | Preset override output colorspace: convert to Rec. 709 colorspace with tone mapping when needed |
| `--output-dir DIR`             | Output directory for exported files                                                             |
| `--naming PATTERN`             | Naming pattern with tokens: `{source}`, `{date}`, `{timecode}`, `{reel}` (default: `{source}`)  |
| `--index-prefix STR`           | Character before frame number for sequences: `.`, `-`, `_` (default: none)                      |
| `--index-min-size N`           | Frame padding 4-12 for sequences (default: auto)                                                |
| `--index-offset VAL`           | Starting frame: `0`, `1`, `offset`, `tc` (default: 0)                                           |

**Examples:**

```bash
# List all available presets
tinman-server export --list-presets

# Export using system preset
tinman-server /path/footage/ export --preset mov_prores422_hq --output-dir /path/exports/

# Export using custom preset JSON file
tinman-server /path/footage/ export --preset /path/my-preset.json --output-dir /path/exports/

# Export at half resolution
tinman-server /path/footage/ export --preset mov_prores422_hq --output-dir /path/exports/ \
  --resolution half

# Export scaled to a maximum width
tinman-server /path/footage/ export --preset mp4_h264_10mbps --output-dir /path/exports/ \
  --max-width 1920

# Export at an exact fixed size
tinman-server /path/footage/ export --preset mp4_h264_10mbps --output-dir /path/exports/ \
  --fixed-size 1920 1080

# Export with a custom target and max bitrate (kbps)
tinman-server /path/footage/ export --preset mp4_h264_10mbps --output-dir /path/exports/ \
  --bitrate 12000 16000

# Export with Rec. 709 colorspace conversion
tinman-server /path/footage/ export --preset mov_prores422_hq --output-dir /path/exports/ \
  --rec709

# Export with custom naming pattern
tinman-server /path/footage/ export --preset mp4_h264_10mbps --output-dir /path/exports/ \
  --naming "{date}_{source}_{timecode}"

# Export image sequence with custom frame numbering
tinman-server /path/file.R3D export --preset imageseq_dpx_10bit_rgb_be \
  --output-dir /path/exports/ --index-prefix "." --index-min-size 6 --index-offset 1

# Export with threading
tinman-server --threads 3 /path/footage/ export --preset mov_prores422_hq --output-dir /path/exports/
```

**System Export Presets**

**Image Sequences:**

* `imageseq_dpx_10bit_rgb_be` - DPX 10-bit RGB Big Endian
* `imageseq_tiff_16bit_rgb` - TIFF 16-bit RGB

**MOV - Apple ProRes:**

* `mov_prores422_proxy` - ProRes 422 Proxy
* `mov_prores422_lt` - ProRes 422 LT
* `mov_prores422` - ProRes 422
* `mov_prores422_hq` - ProRes 422 HQ
* `mov_prores4444_yuv` - ProRes 4444 YUV
* `mov_prores4444_rgb` - ProRes 4444 RGB
* `mov_prores4444_xq_yuv` - ProRes 4444 XQ YUV
* `mov_prores4444_xq_rgb` - ProRes 4444 XQ RGB

**MOV - Avid DNxHR:**

* `mov_dnx_lb` - DNxHR LB
* `mov_dnx_sq` - DNxHR SQ
* `mov_dnx_hq` - DNxHR HQ
* `mov_dnx_hqx` - DNxHR HQX
* `mov_dnx_444` - DNxHR 444

**MOV - Samsung OpenAPV:**

* `mov_apv422_10_sq` - Samsung OpenAPV 422 10-bit SQ
* `mov_apv422_10_lq` - Samsung OpenAPV 422 10-bit LQ
* `mov_apv422_10_hq` - Samsung OpenAPV 422 10-bit HQ
* `mov_apv422_12_sq` - Samsung OpenAPV 422 12-bit SQ
* `mov_apv422_12_lq` - Samsung OpenAPV 422 12-bit LQ
* `mov_apv422_12_hq` - Samsung OpenAPV 422 12-bit HQ
* `mov_apv444_10_uq` - Samsung OpenAPV 4444 10-bit UQ
* `mov_apv444_12_uq` - Samsung OpenAPV 4444 12-bit UQ

**MOV - Passthrough:**

* `mov_passthru` - MOV Passthrough (rewrap without transcoding)

**MP4 - H.264:**

* `mp4_h264_10mbps` - H.264 10 Mbps
* `mp4_h264_20mbps` - H.264 20 Mbps

**MP4 - H.265 (HEVC):**

* `mp4_h265_main_10mbps` - H.265 Main Profile 10 Mbps
* `mp4_h265_main_20mbps` - H.265 Main Profile 20 Mbps
* `mp4_h265_main10_10mbps` - H.265 Main10 Profile 10 Mbps
* `mp4_h265_main10_20mbps` - H.265 Main10 Profile 20 Mbps

**MP4 - H.265 Main 4:2:2 (macOS only):**

* `mp4_h265_main422_8bit_10mbps` - H.265 Main 4:2:2 8-bit 10 Mbps
* `mp4_h265_main422_8bit_20mbps` - H.265 Main 4:2:2 8-bit 20 Mbps
* `mp4_h265_main422_10bit_10mbps` - H.265 Main 4:2:2 10-bit 10 Mbps
* `mp4_h265_main422_10bit_20mbps` - H.265 Main 4:2:2 10-bit 20 Mbps

**MXF OP-Atom - Avid DNxHR:**

* `mxf_opatom_dnx_lb` - MXF OP-Atom DNxHR LB
* `mxf_opatom_dnx_sq` - MXF OP-Atom DNxHR SQ
* `mxf_opatom_dnx_hq` - MXF OP-Atom DNxHR HQ
* `mxf_opatom_dnx_hqx` - MXF OP-Atom DNxHR HQX
* `mxf_opatom_dnx_444` - MXF OP-Atom DNxHR 444

**MXF OP-Atom - Passthrough:**

* `mxf_opatom_passthru` - MXF OP-Atom Passthrough

**MXF OP1a - Apple ProRes:**

* `mxf_op1a_prores422_proxy` - MXF OP1a ProRes 422 Proxy
* `mxf_op1a_prores422_lt` - MXF OP1a ProRes 422 LT
* `mxf_op1a_prores422` - MXF OP1a ProRes 422
* `mxf_op1a_prores422_hq` - MXF OP1a ProRes 422 HQ
* `mxf_op1a_prores4444_yuv` - MXF OP1a ProRes 4444 YUV
* `mxf_op1a_prores4444_rgb` - MXF OP1a ProRes 4444 RGB
* `mxf_op1a_prores4444_xq_yuv` - MXF OP1a ProRes 4444 XQ YUV
* `mxf_op1a_prores4444_xq_rgb` - MXF OP1a ProRes 4444 XQ RGB

**MXF OP1a - Avid DNxHR:**

* `mxf_op1a_dnx_lb` - MXF OP1a DNxHR LB
* `mxf_op1a_dnx_sq` - MXF OP1a DNxHR SQ
* `mxf_op1a_dnx_hq` - MXF OP1a DNxHR HQ
* `mxf_op1a_dnx_hqx` - MXF OP1a DNxHR HQX
* `mxf_op1a_dnx_444` - MXF OP1a DNxHR 444

**MXF OP1a - Sony XAVC (Windows only):**

* `mxf_op1a_xavchd_intra_interlaced_class100cbg` - XAVC HD Intra Interlaced Class 100
* `mxf_op1a_xavchd_intra_progressive_class100cbg` - XAVC HD Intra Progressive Class 100
* `mxf_op1a_xavc2k_intra_class100cbg` - XAVC 2K Intra Class 100
* `mxf_op1a_xavcqfhd_intra_class300cbg` - XAVC QFHD Intra Class 300
* `mxf_op1a_xavcqfhd_intra_class480cbg` - XAVC QFHD Intra Class 480
* `mxf_op1a_xavc4k_intra_class300cbg` - XAVC 4K Intra Class 300
* `mxf_op1a_xavc4k_intra_class480cbg` - XAVC 4K Intra Class 480

**MXF OP1a - Passthrough:**

* `mxf_op1a_passthru` - MXF OP1a Passthrough

***

#### thumbnail

Generate thumbnail JPEG images with extensive control over size, quality, timing, and naming. **This command is currently free**

**Options:**

| Option                    | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| `--output-dir DIR`        | Output directory for thumbnails (required, created if needed)                   |
| `--size WIDTH`            | Max width in pixels, height maintains aspect (120-1024, default: 320)           |
| `--quality N`             | JPEG quality 1-100 (default: 85)                                                |
| `--startframe FRAME`      | Starting frame number (default: 0, overrides --starttimecode)                   |
| `--starttimecode TC`      | Starting timecode (default: first frame)                                        |
| `--time-interval SECONDS` | Generate thumbnail every N seconds (default: single frame)                      |
| `--time-count N`          | Max number of thumbnails per file (default: 1)                                  |
| `--position-count N`      | Generate N evenly distributed thumbnails (min: 2, overrides time-based options) |
| `--rec709`                | Convert thumbnails to Rec. 709 colorspace                                       |
| `--rec709tonemap`         | Convert thumbnails to Rec. 709 colorspace with tone mapping when needed         |
| `--usesubdirs`            | Create subdirectory per source file (batch mode only)                           |
| `--fileoverwrite`         | Overwrite existing thumbnail files (default: skip with error)                   |
| `--nameprefix NAME`       | Prefix to add before source filename (default: none)                            |
| `--nameseparator SEP`     | Separator: none, dash, dot, underscore (default: underscore)                    |
| `--nameindex TYPE`        | Index type: frame, timecode, sequence (default: sequence)                       |

**Position-based generation examples:**

* `--position-count 3` = 0%, 50%, 100% (start, middle, end)
* `--position-count 6` = 0%, 20%, 40%, 60%, 80%, 100%

**Examples:**

```bash
# Single thumbnail per file at default size (320px)
tinman-server /path/footage/ thumbnail --output-dir /path/thumbs/

# Three evenly distributed thumbnails (start/middle/end)
tinman-server /path/footage/ thumbnail --output-dir /path/thumbs/ --position-count 3

# Six evenly distributed thumbnails
tinman-server /path/footage/ thumbnail --output-dir /path/thumbs/ --position-count 6

# Five thumbnails with 1 second intervals, organized in subdirectories
tinman-server /path/footage/ thumbnail --output-dir /path/thumbs/ \
  --time-count 5 --time-interval 1.0 --usesubdirs

# Custom naming with prefix and timecode index
tinman-server /path/file.R3D thumbnail --output-dir /path/thumbs/ \
  --nameprefix Dailies --nameindex timecode

# High resolution with Rec. 709 Tone-Mapping conversion
tinman-server /path/file.braw thumbnail --output-dir /path/thumbs/ \
  --startframe 100 --size 1024 --quality 95 --rec709tonemap
```

***

#### copy

Copy files with checksum verification. **This command is currently free**

**Options:**

| Option             | Description                              |
| ------------------ | ---------------------------------------- |
| `--output-dir DIR` | Destination directory (required)         |
| `--overwrite`      | Overwrite existing files (default: skip) |

**Examples:**

```bash
# Copy single file with verification
tinman-server /path/input.R3D copy --output-dir /path/backup/

# Copy folder preserving structure
tinman-server /path/footage/day1/ copy --output-dir /path/backup/day1/

# Copy with threading for speed
tinman-server --threads 5 /path/footage/ copy --output-dir /path/backup/

# Overwrite existing files
tinman-server /path/footage/ copy --output-dir /path/backup/ --overwrite
```

***

### Command Chaining

Multiple commands can be executed in a single invocation:

```bash
# Generate both metadata report and thumbnails
tinman-server /path/input.R3D metadata --output-dir /path/reports/ thumbnail --output-dir /path/thumbs/
```

### Progress Output

By default, Tin Man Server outputs JSON-formatted progress for automation:

```bash
# JSON progress (default)
tinman-server /path/footage/ metadata --output-dir /path/reports/

# Human-readable progress
tinman-server --progress=no-json /path/footage/ metadata --output-dir /path/reports/
```

The JSON progress output includes file processing status, progress percentage, errors and warnings, operation results, and timing metrics. Progress updates are throttled to 10% increments for batch operations to reduce output volume.

### Claude Cowork

Tin Man Server also includes a Claude Cowork plugin that exposes all commands through natural language in Claude AI. See the [GitHub repository](https://github.com/calibratedsoftware/tinman-server-cowork) for installation.

### Other MCP Clients

To connect Tin Man Server to any MCP-compatible client, add the following entry to your client's MCP configuration file.

**Windows:**

```json
"tinman-server": {
  "command": "C:\\Program Files\\Calibrated Software\\Tin Man\\python\\python.exe",
  "args": ["C:\\Program Files\\Calibrated Software\\Tin Man\\Server\\tinman_server_mcp.cpython-310.pyc"]
}
```

**macOS:**

```json
"tinman-server": {
  "command": "/Applications/Calibrated Tin Man.app/Contents/PlugIns/Frameworks/Python.framework/Versions/3.10/bin/python3",
  "args": ["/Applications/Calibrated Tin Man.app/Contents/Server/tinman_server_mcp.cpython-310.pyc"]
}
```

### Tips

* Press `Ctrl+C` to cancel any running operation
* Use `--threads` to process multiple files concurrently (max 5)
* The `copy` command is currently free
* The `thumbnail` command is currently free
* File inputs are processed recursively by default; use `--no-recursive` to process only top-level files


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.calibratedsoftware.com/tin-man/tin-man-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.