Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 18 additions & 56 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,22 @@
# Millwright

Millwright is a self-hosted automation interface for [FFmpeg](https://ffmpeg.org/). It can be used to automate
media processing tasks, such as changing video codecs, containers, audio tracks, and subtitles. You can process
individual files or let Millwright handle new files automatically.
Millwright is a self-hosted [FFmpeg](https://ffmpeg.org/) automation tool. Convert individual files or
apply rules to a library to change codecs, containers, audio tracks, and subtitles.

> [!WARNING]
> Millwright is in beta testing phase and may have bugs or incomplete features.
>
> I personally tested the app on my own library and it worked as expected at least for nvidia, qsv and software encoders.
> Unfortunately, I cannot guarantee that it will work perfectly for all setups or encoders without actual testing on
> those setups. **AMD** encoders may also work, but I haven't tested them as i dont have the necessary hardware.
> I've tested NVIDIA, Intel QSV, and software encoders on my own library AMD encoders are not tested.

### If you like my work, you might also like my other projects:

* [YTPTube](https://github.com/arabcoders/ytptube): Media download manager, automation interface, and media library preparation layer for yt-dlp.
* [WatchState](https://github.com/arabcoders/watchstate): Self-hosted service to sync your media servers without relying on 3rd-party external services.
* [WatchState](https://github.com/arabcoders/watchstate): Sync your media servers without relying on 3rd parties.
* [YTPTube](https://github.com/arabcoders/ytptube): Media downloader, automation, and library manager for yt-dlp.
* [DCompose](https://github.com/arabcoders/dcompose): Manage your servers/nodes compose stacks from one WebUI.

## Screenshots

Dashboard:

![Dashboard](ui/public/images/screenshots/dashbaord.jpg)
![Dashboard](ui/public/images/screenshots/dashboard.jpg)

Statistics:

Expand All @@ -32,16 +28,11 @@ Job details:

## How it works

1. Add your media folders as a **Library**.
2. Choose a **Flow** that describes which files to process and what to change.
3. Preview the flow to see which files match.
4. A **Node** runs the conversion. Millwright checks the result before replacing the library file.

You can add nodes on other machines to share the conversion work.
Add a **Library** and preview a **Flow** to see which files it would change. **Nodes** run conversions
on the server or on other machines. Millwright checks the output before replacing the original.

> [!WARNING]
> Millwright can replace your media files. Keep originals in Trash while trying a new flow, and maintain
> a separate backup of media you can't replace.
> [Keep originals in Trash](docs/recovery.md#retain-originals) while trying a new flow.

## What you can do

Expand All @@ -54,51 +45,22 @@ You can add nodes on other machines to share the conversion work.
- Restore retained originals and track disk space saved.
- Receive import notifications from Sonarr or Radarr and notify them after a conversion.

See [Using Millwright](docs/usage.md) for the workflow and [Flow recipes](docs/recipes.md) for examples.

## Install

Run the installer in your chosen installation directory and enter your media folder when prompted:

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/arabcoders/millwright/dev/install.sh)
```

See the [installation guide](docs/installation.md) for requirements, storage, GPU access, and remote nodes.

After starting Millwright, open `http://<server-ip>:8000`, create your account, claim the pending node on **Nodes**, and [add your first library](docs/usage.md#add-a-library).

## Security

> [!IMPORTANT]
> All accounts and API key holders have administrator access and can replace library files.
> Only give access to people you trust.

Use HTTPS for network access and install plugins only from trusted sources. Read the
[security policy](SECURITY.md) before exposing an instance and use
[private vulnerability reporting](https://github.com/arabcoders/millwright/security/advisories/new)
to report security problems.

## Documentation

Please see - [Documentation index](docs/README.md).
Follow the [installation guide](docs/installation.md) to run the installer, claim a node, and add
your first library. See the [documentation index](docs/README.md) for setup guides and references.

## Project Policy

Millwright is a personal-first project. Contributions are welcome ONLY after approval from the maintainer following
prior discussion. Any unsolicited pull requests will be declined. Read [CONTRIBUTING](CONTRIBUTING.md) before starting
any work to avoid wasting your and the maintainer's time.

AI-assisted tools have been used in this project and will continue to be used where I find them useful. This project is
built for my own needs and use cases, and I maintain it according to my own preferences.

You're welcome to use it if it works for you, but I won't change the project's development approach. If the use of
AI-assisted tools is a deal-breaker for you, this project may not be the right fit for you. Feel free to build your own.
Millwright is built for my own needs and use cases first. Discuss contributions with me before starting any work that i
may decline to accept. Read [CONTRIBUTING.md](CONTRIBUTING.md). I use AI tools in this project. You're welcome to use the
project if it works for you. However, if you object to that, then this project is not good fit for you. Build your own
using technologies you approve of.

## Community

For short questions, join the [Discord server](https://discord.gg/G3GpVR8xpb). Millwright is maintained as a solo
project, so replies may take some time.

If you want to support the work financially, please donate to a children's charity such as
[Make-A-Wish](https://worldwish.org) international instead.
If you want to support the work financially, please donate to a children's charity such as
[Make-A-Wish international](https://worldwish.org) instead.
6 changes: 2 additions & 4 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Millwright documentation

## Getting started
- [project overview](../README.md): Basic introduction to Millwright.

- [Installation](installation.md): Run Millwright and give it access to your media.
- [Using Millwright](usage.md): Add a library, choose a flow, and try your first conversion.
- [Using Millwright](usage.md): Set up libraries, preview flows, and control automatic processing.
- [Flow recipes](recipes.md): Examples you can adapt to your library.

## Setup and maintenance
Expand All @@ -21,5 +21,3 @@
- [Development guide](development.md): Build containers, test OIDC, and change the database schema.

For HTTP endpoints and the OpenAPI schema, [enable the API reference](installation.md#api-reference).
It's off by default.

34 changes: 8 additions & 26 deletions docs/authentication.md
Original file line number Diff line number Diff line change
@@ -1,30 +1,18 @@
# Authentication

Create your account the first time you open Millwright. You can sign in with that username and password,
or add OIDC to use an existing identity provider.
Account registration closes after the first account is created. See the
[security policy](../SECURITY.md#who-should-have-access) for access limits.

Every account has full access to the instance. There are no read-only accounts or per-library permissions.
## Recover access

## Create the first account

Open the web interface and choose a username and password. Finish this step before making Millwright
accessible to other people. Account registration closes after the first account is created.

## Change your password

Open **Account**, enter your current password, and enter the new password twice. Choose **Change password**.
You stay signed in on this browser. Your other browsers and devices must sign in again.

## Reset a forgotten password

You need terminal access to the server. From the directory containing `compose.yml`, run:
Changing your password in **Account** signs out other devices but keeps the current browser signed in.
If you've forgotten your password, run this from the directory containing `compose.yml`:

```bash
docker compose exec server millwright auth reset-password --username owner
```

Replace `owner` with your username. Enter the new password twice when prompted, then sign in again.
The reset signs that account out on all devices.
Replace `owner` with your username. A reset signs that account out on all devices.

## Configure OIDC

Expand Down Expand Up @@ -66,11 +54,5 @@ Restart Millwright, then test both password and OIDC login. If you use a reverse
Remove the person's access at the provider. To end existing Millwright logins too, reset the mapped
account's password. This signs everyone using that account out.

Changing a local password doesn't stop someone who still has provider access from signing in through
OIDC again. Likewise, logging out of Millwright doesn't log you out of the provider.

## Back up your account

Configuration exports don't include accounts. Include PostgreSQL in your
[backup plan](recovery.md#database-and-filesystem-backups) if you want to preserve your login when
recovering the instance.
Someone with provider access can still sign in through OIDC after a password reset. Signing out of
Millwright doesn't sign you out of the provider.
18 changes: 2 additions & 16 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,6 @@

For the standard setup and check commands, see [Contributing](../CONTRIBUTING.md).

## Frontend runtime

Vue type checking requires Node.js because
[`vue-tsc` doesn't work under Bun](https://github.com/oven-sh/bun/issues/4754).
This also affects the type check during production builds.

## Keep development data

In `compose.dev.yml`, the `postgres` and `postgres-test` services use temporary storage. To keep
Expand All @@ -32,21 +26,13 @@ Then start the server and a local node from the repository root:
uv run python run.py --role all
```

Open `http://localhost:8000` and claim the pending node on **Nodes**. Use `--role server` if you don't
need a local node.
The built interface is at `http://localhost:8000`.

For a separate source node, set `MW_NODE_SERVER_URL` and `MW_NODE_WORKSPACE_DIR`, then run
`uv run python -m node` from `node/`. Claim it on **Nodes**. See
[Add a node](installation.md#add-a-node) for connection and shared-storage setup.

## Use the CLI

Run CLI commands from `server/`:

```bash
uv run millwright libraries list
uv run millwright auth reset-password --username owner
```
Run `uv run millwright` from `server/` for [CLI access](usage.md#command-line-and-api-access).

## Build the container

Expand Down
36 changes: 11 additions & 25 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,14 @@ tools are included in the image.
Run this in the directory where you want to keep Millwright:

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/arabcoders/millwright/HEAD/install.sh)
bash <(curl -fsSL https://raw.githubusercontent.com/arabcoders/millwright/dev/install.sh)
```

Enter your media folder when prompted. The installer asks before starting compose file. Press Enter to skip startup.
Rerunning it keeps your existing configuration and credentials.
Enter your media folder and confirm startup. Rerunning the installer keeps existing configuration and
credentials.

Open `http://YOUR_SERVER_IP:8000` and create your account. Use your server's IP address, or
`http://localhost:8000` if your browser is on the same machine.

Open **Nodes** and click **Claim** on the pending node. Then [add a library](usage.md#add-a-library),
using `/media` for the folder you selected during installation.
Open `http://<server-ip>:8000` and create your account before exposing the service. Claim the pending
node under **Nodes**, then [add a library](usage.md#add-a-library) using `/media`.

## Update Millwright

Expand All @@ -33,12 +30,9 @@ Update any nodes on other machines too, using the same image version. See

## Configuration and storage

Change processing limits, scanning, playback, and history retention under **Configuration -> Settings**.
These changes don't need a restart.

Other server settings are in `config/millwright/config.toml` inside your installation directory.
See the [configuration example](../server/src/server/config.example.toml) for available options.
After editing this file, restart the server:
**Configuration -> Settings** changes apply without restarting. For startup options, see the
[configuration example](../server/src/server/config.example.toml). After editing
`config/millwright/config.toml`, restart the server:

```bash
docker compose restart server
Expand All @@ -58,8 +52,6 @@ Accounts, settings, and job history are stored in the PostgreSQL volume `db-data
directories. Include the database in your [backups](recovery.md#database-and-filesystem-backups).
Don't use `docker compose down --volumes` for updates. It deletes the database volume.

For disk space problems, see [Workspace cleanup](recovery.md#workspace-cleanup).

To move retained originals, let active work and recovery finish, then stop the server and nodes. Copy
the complete trash directory to the new location. Mount it writable in the server container and set
`trash_dir` in `config/millwright/config.toml` to its container path before starting Millwright again.
Expand Down Expand Up @@ -121,16 +113,12 @@ Start the node:
docker compose up -d --pull always
```

Open **Nodes** in the web interface and click **Claim**. Use **Edit** to set the node's processing limits.

New node registration is enabled by default. The **Allow new nodes** switch on **Nodes** stops new
registration.
Claim the pending node under **Nodes**. If it doesn't appear, check that **Allow new nodes** is on.

Keep each node's `node-config` and `node-data` directories separate. The node saves its credentials
there and reconnects automatically after a restart. Only the workspace is shared.

You can keep or remove the node on the server machine. For connections across an untrusted network,
use [HTTPS](#reverse-proxies) for the server address.
Across an untrusted network, use an [HTTPS server address](#reverse-proxies).

## Hardware acceleration

Expand Down Expand Up @@ -210,15 +198,13 @@ For OIDC login, follow the callback instructions in [Authentication](authenticat

### API reference

To enable API documentation, add this at the top level of `config/millwright/config.toml` and restart
the server:
The API reference is off by default. Enable it in `config/millwright/config.toml` and restart the server:

```toml
enable_docs = true
```

Open `/api/docs` for Swagger, `/api/redoc` for ReDoc, or `/api/openapi.json` for the schema.
Set `enable_docs = false` and restart to turn them off.

### File access errors

Expand Down
28 changes: 5 additions & 23 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,18 +60,14 @@ ones. Reinstalling an uploaded ID replaces that uploaded plugin.

## Choose a plugin kind

The kind determines which outputs appear in the flow editor:

| Kind | Use it for | Decisions and ports |
| ----------- | ---------------------------------------------------------- | -------------------------------------- |
| `filter` | Allow or reject input | `match`, `veto` |
| `inspector` | Inspect media before or after processing | `match`, `veto`, `skip` |
| `transcode` | Request a processing stage | `plan`, `skip` |
| `action` | Request an action without selecting the flow branch itself | `actions`, followed by the `next` port |

For example, a duration inspector returns `match` when the next step should run. A transcode returns
`skip` if the file already meets its requirements. Include a readable `reason` with `skip` and `veto`
so someone opening the job can understand the decision.
Include a `reason` with `skip` and `veto` so the job log explains the decision.

Return an error when the plugin can't make a valid decision:

Expand Down Expand Up @@ -119,22 +115,9 @@ settings or records need a migration. Each saved plugin node records its own `co
nodes without that field are version `1`. New steps use the installed plugin's current configuration
version. Actions emitted by plugins also carry `plugin_id` and `config_version` metadata.

Declare migrations in `plugin.toml`, alongside the other manifest fields. For example, the external
notification plugin's configuration version `2` renames its step, action, event, progress field, and
delivery prefix:

```toml
id = "action.notify_external"
version = "1.1.0"
config_version = 2
migrations = [{ from_version = 1, to_version = 2, changes = [
{ type = "rename_plugin", from = "action.notify_media_manager", to = "action.notify_external" },
{ type = "rename_action", from = "notify_media_manager", to = "notify_external" },
{ type = "rename_event", from = "media_manager_notification", to = "external_notification" },
{ type = "rename_field", scope = "event", from = "refresh", to = "progress" },
{ type = "rename_target_prefix", from = "media-manager:", to = "external:" },
] }]
```
Declare `migrations` in `plugin.toml`. The
[external notification manifest](../plugins/action.notify_external/plugin.toml) shows a version
transition using each supported rename.

The supported changes are:

Expand Down Expand Up @@ -167,8 +150,7 @@ configuration versions rather than applying migrations itself.

If you retry a finished job, its saved execution configuration is migrated when the retry is requested.

Unrelated configurations stay unchanged. After a successful commit, logs identify the plugin, record,
version transition, and changes applied.
Logs identify which records were migrated and what changed.

## Read media information

Expand Down
Loading