From f936c086cce0074e34220e65f48ba5d34566dcc9 Mon Sep 17 00:00:00 2001 From: djdev0010 <41651107+djdev0010@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:09:30 -0500 Subject: [PATCH 1/2] update documentation --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CLAUDE.md | 10 +- CODESTANDARDS.md | 3 +- CONTRIBUTING.md | 31 +- README.md | 71 ++-- docs/ARCHITECTURE.md | 304 ------------------ docs/USER_GUIDE.md | 102 ------ .../architecture/cross-cutting-concerns.md | 67 ++++ docs/contribute/architecture/invariants.md | 39 +++ docs/contribute/architecture/overview.md | 154 +++++++++ docs/contribute/concepts/ai-icon-search.md | 25 ++ docs/contribute/concepts/app-startup.md | 49 +++ docs/contribute/concepts/card-model.md | 53 +++ .../concepts/claude-desktop-connector.md | 49 +++ docs/contribute/concepts/community-icons.md | 31 ++ docs/contribute/concepts/icon-matching.md | 103 ++++++ docs/contribute/concepts/import-pipeline.md | 83 +++++ .../contribute/concepts/library-and-editor.md | 58 ++++ docs/contribute/concepts/media-uploads.md | 38 +++ .../concepts/navigation-and-commands.md | 68 ++++ .../concepts/podcast-feed-import.md | 37 +++ .../concepts/read-and-save-cards.md | 59 ++++ .../contribute/concepts/sign-in-and-tokens.md | 64 ++++ docs/contribute/concepts/track-search.md | 28 ++ .../contribute/concepts/yoto-http-pipeline.md | 34 ++ .../concepts/yoto-player-control.md | 74 +++++ docs/contribute/how-to/add-card-field.md | 33 ++ .../how-to/add-claude-desktop-tool.md | 33 ++ docs/contribute/how-to/add-domain-logic.md | 36 +++ docs/contribute/how-to/add-navigation-page.md | 54 ++++ docs/contribute/how-to/add-panel.md | 43 +++ .../how-to/add-setting-or-secret.md | 35 ++ docs/contribute/how-to/call-yoto-endpoint.md | 38 +++ .../contribute/how-to/improve-icon-matches.md | 30 ++ .../how-to/render-screen-snapshots.md | 26 ++ .../reference/design-decisions.md} | 23 +- docs/contribute/reference/glossary.md | 25 ++ docs/design/app.md | 295 ----------------- docs/design/icon-matching.md | 157 --------- docs/design/import.md | 132 -------- docs/design/players.md | 85 ----- docs/design/yoto-client.md | 269 ---------------- docs/how-to.md | 217 ------------- docs/index.md | 49 +++ docs/toc.yml | 116 +++++++ docs/user/build-the-app.md | 45 +++ docs/user/edit-playlists.md | 56 ++++ docs/user/import-folders.md | 38 +++ docs/user/import-podcast-feed.md | 40 +++ docs/user/library-and-search.md | 40 +++ docs/user/match-icons.md | 55 ++++ docs/user/overview.md | 35 ++ docs/user/play-audio.md | 45 +++ docs/user/quickstart.md | 44 +++ docs/user/reference/data-locations.md | 42 +++ docs/user/use-with-claude-desktop.md | 43 +++ src/OpenMyo.App/README.md | 105 +----- 57 files changed, 2196 insertions(+), 1724 deletions(-) delete mode 100644 docs/ARCHITECTURE.md delete mode 100644 docs/USER_GUIDE.md create mode 100644 docs/contribute/architecture/cross-cutting-concerns.md create mode 100644 docs/contribute/architecture/invariants.md create mode 100644 docs/contribute/architecture/overview.md create mode 100644 docs/contribute/concepts/ai-icon-search.md create mode 100644 docs/contribute/concepts/app-startup.md create mode 100644 docs/contribute/concepts/card-model.md create mode 100644 docs/contribute/concepts/claude-desktop-connector.md create mode 100644 docs/contribute/concepts/community-icons.md create mode 100644 docs/contribute/concepts/icon-matching.md create mode 100644 docs/contribute/concepts/import-pipeline.md create mode 100644 docs/contribute/concepts/library-and-editor.md create mode 100644 docs/contribute/concepts/media-uploads.md create mode 100644 docs/contribute/concepts/navigation-and-commands.md create mode 100644 docs/contribute/concepts/podcast-feed-import.md create mode 100644 docs/contribute/concepts/read-and-save-cards.md create mode 100644 docs/contribute/concepts/sign-in-and-tokens.md create mode 100644 docs/contribute/concepts/track-search.md create mode 100644 docs/contribute/concepts/yoto-http-pipeline.md create mode 100644 docs/contribute/concepts/yoto-player-control.md create mode 100644 docs/contribute/how-to/add-card-field.md create mode 100644 docs/contribute/how-to/add-claude-desktop-tool.md create mode 100644 docs/contribute/how-to/add-domain-logic.md create mode 100644 docs/contribute/how-to/add-navigation-page.md create mode 100644 docs/contribute/how-to/add-panel.md create mode 100644 docs/contribute/how-to/add-setting-or-secret.md create mode 100644 docs/contribute/how-to/call-yoto-endpoint.md create mode 100644 docs/contribute/how-to/improve-icon-matches.md create mode 100644 docs/contribute/how-to/render-screen-snapshots.md rename docs/{design/decisions.md => contribute/reference/design-decisions.md} (63%) create mode 100644 docs/contribute/reference/glossary.md delete mode 100644 docs/design/app.md delete mode 100644 docs/design/icon-matching.md delete mode 100644 docs/design/import.md delete mode 100644 docs/design/players.md delete mode 100644 docs/design/yoto-client.md delete mode 100644 docs/how-to.md create mode 100644 docs/index.md create mode 100644 docs/toc.yml create mode 100644 docs/user/build-the-app.md create mode 100644 docs/user/edit-playlists.md create mode 100644 docs/user/import-folders.md create mode 100644 docs/user/import-podcast-feed.md create mode 100644 docs/user/library-and-search.md create mode 100644 docs/user/match-icons.md create mode 100644 docs/user/overview.md create mode 100644 docs/user/play-audio.md create mode 100644 docs/user/quickstart.md create mode 100644 docs/user/reference/data-locations.md create mode 100644 docs/user/use-with-claude-desktop.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 6b63d83..3ced185 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,7 +12,7 @@ - [ ] Tests added or updated; bug fixes include a failing-first test (section 9) - [ ] UI changes follow section 8 (compiled bindings, Discord-style design, keyboard, accessibility) - [ ] New packages justified below and added only to `Directory.Packages.props` (section 11) -- [ ] README / `docs/ARCHITECTURE.md` / CODESTANDARDS updated if behaviour or rules changed +- [ ] README / `docs/` pages (and `docs/toc.yml`) / CODESTANDARDS updated if behaviour or rules changed ## Notes for reviewers diff --git a/CLAUDE.md b/CLAUDE.md index fe02484..15d8c0a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,9 +6,11 @@ Guidance for Claude (and other AI coding agents) working in this repository. 1. **[CODESTANDARDS.md](CODESTANDARDS.md)** is mandatory. Every change must follow it, especially the dependency rules (§1), size limits (§2), async rules (§5) and UI rules (§8). -2. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): what OpenMyo is, its containers, the code map and the - invariants. Details per area are in [docs/design/](docs/design); step-by-step guides for common - changes are in [docs/how-to.md](docs/how-to.md). +2. [docs/contribute/architecture/overview.md](docs/contribute/architecture/overview.md): what OpenMyo is + its containers and [projects](docs/contribute/architecture/overview.md#projects), with the + [invariants](docs/contribute/architecture/invariants.md) beside it. Details per area are in + [docs/contribute/concepts/](docs/contribute/concepts); step-by-step guides for common changes are in + [docs/contribute/how-to/](docs/contribute/how-to). [docs/toc.yml](docs/toc.yml) lists every page. ## What this is @@ -36,7 +38,7 @@ eng/check-file-sizes.sh # enforce CODESTANDARDS §2 file limits | Yoto HTTP calls, JSON mapping, OAuth | `src/OpenMyo.Yoto//` | | Claude prompt / API call | `src/OpenMyo.Claude/` | | Keychain/DPAPI, tags, settings, paths | `src/OpenMyo.Infrastructure//` | -| Screens and view models, styles | `src/OpenMyo.App/Screens//` (view beside view model), `src/OpenMyo.App/Styles/`; see `src/OpenMyo.App/README.md` and `docs/how-to.md` | +| Screens and view models, styles | `src/OpenMyo.App/Screens//` (view beside view model), `src/OpenMyo.App/Styles/`; see `docs/contribute/concepts/navigation-and-commands.md` and `docs/contribute/how-to/` | | Service registration | each project's `ServiceCollectionExtensions.cs`; wired in `src/OpenMyo.App/Composition/` | ## Rules of thumb for agents diff --git a/CODESTANDARDS.md b/CODESTANDARDS.md index 1f8a277..f4ec389 100644 --- a/CODESTANDARDS.md +++ b/CODESTANDARDS.md @@ -207,5 +207,6 @@ Names are whole words (`playlist`, not `pl`); loop indexes and lambdas over obvi - Small, focused commits in imperative mood: `Add trigram icon index`. - One logical change per pull request; CI (build + tests + size check on macOS and Windows) must pass. -- Update `README.md`, `docs/ARCHITECTURE.md`, `docs/design/`, `docs/how-to.md` or this file in the same PR +- Update `README.md`, the pages under `docs/` (user pages for behaviour, `docs/contribute/` for design and + workflow, plus `docs/toc.yml` for new pages) or this file in the same PR when behaviour or rules change. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bab283b..b5a4983 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,21 +6,26 @@ truth for review. AI agents should also read [CLAUDE.md](CLAUDE.md). ## Setup 1. Install the .NET 10 SDK (see `global.json`). -2. Clone the repository and run `dotnet build OpenMyo.sln`. -3. To run the app, register your own Yoto application as described in the [README](README.md) and - paste the client id into Settings. +1. Clone the repository and run `dotnet build OpenMyo.sln`. +1. To run the app, register your own Yoto app as described in + [Quickstart: Sign in and run OpenMyo](docs/user/quickstart.md) and paste the client id into + **Settings**. ## Start here -- **New to the code:** [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), the system, code map and invariants. -- **Adding a page or panel:** [src/OpenMyo.App/README.md](src/OpenMyo.App/README.md), then - [How to add a page to the sidebar](docs/how-to.md#how-to-add-a-page-to-the-sidebar). -- **Adding a Yoto API call or card field:** [docs/how-to.md](docs/how-to.md#how-to-call-a-new-yoto-endpoint). -- **Adding a setting or secret:** [docs/how-to.md](docs/how-to.md#how-to-add-a-setting-or-a-secret). -- **Adding a Claude Desktop tool:** [docs/how-to.md](docs/how-to.md#how-to-add-a-claude-desktop-tool). -- **Icon matches look wrong:** [How to improve icon matches](docs/how-to.md#how-to-improve-icon-matches), - background in [docs/design/icon-matching.md](docs/design/icon-matching.md). -- **Changing import, sign-in or saving:** the matching explanation in [docs/design/](docs/design). +| If you're… | Read | +|---|---| +| New to the code | [Architecture overview](docs/contribute/architecture/overview.md), then the [invariants](docs/contribute/architecture/invariants.md) | +| Adding a page or panel | [Navigation and commands](docs/contribute/concepts/navigation-and-commands.md), then [Add a page to the navigation rail](docs/contribute/how-to/add-navigation-page.md) or [Add a panel to a screen](docs/contribute/how-to/add-panel.md) | +| Adding a Yoto API call or card field | [Call a new Yoto endpoint](docs/contribute/how-to/call-yoto-endpoint.md), [Store a new card field](docs/contribute/how-to/add-card-field.md) | +| Adding a setting or secret | [Add a setting or a secret](docs/contribute/how-to/add-setting-or-secret.md) | +| Adding a Claude Desktop tool | [Add a Claude Desktop tool](docs/contribute/how-to/add-claude-desktop-tool.md) | +| Fixing icon matches that look wrong | [Improve icon matches](docs/contribute/how-to/improve-icon-matches.md), background in [Icon matching](docs/contribute/concepts/icon-matching.md) | +| Changing import, sign-in or saving | The matching page under [docs/contribute/concepts/](docs/contribute/concepts) | + +Every page is listed in [docs/toc.yml](docs/toc.yml). New pages follow the Microsoft Learn conventions the +existing ones use: front matter with `title`, `description`, `ms.topic` and `ms.date`, one topic per page, +and a `## Related content` section at the end. Add each new page to `docs/toc.yml`. ## Workflow @@ -49,7 +54,7 @@ CI runs the same steps on macOS and Windows and must pass before merge. - I/O is async with a trailing `CancellationToken`; bounded parallelism (section 5) - Efficiency: streaming, caching and typed `HttpClient`s (section 6) - No secrets in files, logs or URLs; external input validated (section 7) -- UI follows MVVM, compiled bindings, Discord-style design design, keyboard and accessibility rules (section 8) +- UI follows MVVM, compiled bindings, Discord-style design, keyboard and accessibility rules (section 8) - Tests follow `Method_Scenario_ExpectedResult` and never touch the network or real keychains (section 9) - Public types have useful XML docs; no commented-out code or unlinked TODOs (section 10) diff --git a/README.md b/README.md index 0e53057..5fd6308 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,38 @@ # OpenMyo An unofficial, open-source desktop app for managing Yoto "Make Your Own" (MYO) playlists on macOS and -Windows. It imports folders of audio as playlists, cleans up track titles and matches icons. It -searches every playlist for a track by title and can play any track on one of your Yoto players. Claude -Desktop can also use it to rename tracks, pick icons, find tracks and play them on a player. Written in C# with .NET 10 and Avalonia 11. +Windows. It imports folders of audio and podcast feeds as playlists, cleans up track titles and matches +icons. It searches every playlist for a track by title and can play any track on this computer or on one +of your Yoto players. Claude Desktop can also use it to rename tracks, pick icons, find tracks and play +them on a player. Written in C# with .NET 10 and Avalonia 11. -OpenMyo is not affiliated with or endorsed by Yoto. Each user signs in with their own Yoto account and -their own registered Yoto app. +> [!NOTE] +> OpenMyo isn't affiliated with or endorsed by Yoto. Each user signs in with their own Yoto account and +> their own registered Yoto app. -For what the app does and how to use it, see the [user guide](docs/USER_GUIDE.md). +## Documentation -## Requirements +All documentation is in [docs/](docs/index.md): -- [.NET 10 SDK](https://dotnet.microsoft.com/download) (exact version pinned in `global.json`) -- macOS or Windows -- A Yoto account +- **Use OpenMyo:** [What is OpenMyo?](docs/user/overview.md), + [Quickstart: Sign in and run OpenMyo](docs/user/quickstart.md), + [Build the app](docs/user/build-the-app.md), and one guide per feature. +- **Contribute:** [Architecture overview](docs/contribute/architecture/overview.md), + [concepts](docs/contribute/concepts), [how-to guides](docs/contribute/how-to) and + [reference](docs/contribute/reference). -## Run it +## Get started -1. Register an app at as a **public client** with the redirect URI - `http://127.0.0.1:8787/callback`, and copy its client id. -2. Start the app: +You need the [.NET 10 SDK](https://dotnet.microsoft.com/download) (exact version pinned in +`global.json`), macOS or Windows, and a Yoto account. - ```bash - dotnet run --project src/OpenMyo.App - ``` - -3. Open **Settings**, paste the client id and sign in. - -## Build the app - -There are no prebuilt downloads yet, so build the app yourself. Each command below makes one file that -runs without .NET installed, in `publish/`: - -| Platform | Command | Output | -|---|---|---| -| Windows | `dotnet publish src/OpenMyo.App -c Release -r win-x64 -o publish` | `OpenMyo.exe` | -| macOS, Apple silicon | `dotnet publish src/OpenMyo.App -c Release -r osx-arm64 -o publish` | `OpenMyo` | -| macOS, Intel | `dotnet publish src/OpenMyo.App -c Release -r osx-x64 -o publish` | `OpenMyo` | - -You can build for either platform from either one. Things to know: - -- On macOS the result is a plain executable, not an `.app` bundle. Run it from Terminal - (`./publish/OpenMyo`) or double-click it in Finder. -- The builds aren't code-signed. Windows SmartScreen and macOS Gatekeeper will warn the first time a - copy downloaded from elsewhere is opened. -- The first launch takes a few seconds longer while the app unpacks itself. +```bash +dotnet run --project src/OpenMyo.App +``` -To use it with Claude Desktop, open the built app and choose **Settings → Connect to Claude Desktop**. -Claude Desktop then launches that same file, so keep it where it is or connect again after moving it. +Before you can sign in, register your own Yoto app. Follow +[Quickstart: Sign in and run OpenMyo](docs/user/quickstart.md). There are no prebuilt downloads yet; +to make a standalone executable, see [Build the app](docs/user/build-the-app.md). ## Build and test @@ -65,15 +49,16 @@ CI runs the same three steps on macOS and Windows. ``` src/ OpenMyo.Core/ Domain logic: playlists, icons, import, publishing, library - OpenMyo.Yoto/ Yoto API client, OAuth, JSON mapping + OpenMyo.Yoto/ Yoto API client, OAuth, JSON mapping, player control OpenMyo.Claude/ Optional Claude icon keyword suggestions OpenMyo.Mcp/ MCP server for Claude Desktop - OpenMyo.Infrastructure/ Audio tags, Keychain/DPAPI, settings, paths + OpenMyo.Infrastructure/ Audio tags and playback, Keychain/DPAPI, settings, paths OpenMyo.App/ Avalonia UI and composition root tests/ One test project per production project with logic +tools/OpenMyo.Snapshots/ Renders screens to PNG without signing in ``` -[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) explains how these fit together. +The [architecture overview](docs/contribute/architecture/overview.md#projects) explains how these fit together. ## Contributing diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index 2ede3a5..0000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -description: "Architecture overview of OpenMyo: system context, containers, code map, invariants and cross-cutting concerns; read when starting work in the repo or deciding where a change belongs." ---- - -# Architecture - -## Bird's eye view - -OpenMyo is a desktop app for macOS and Windows that manages Yoto "Make Your Own" (MYO) playlists. It -turns folders of audio files into playlists on the user's Yoto account, and tidies existing playlists: -titles, track order, covers and the 16×16 pixel icon shown for each track. - -OpenMyo has no server and keeps no playlists of its own. Every playlist lives on Yoto as a JSON document -called a **card**. OpenMyo reads cards, changes them, and saves them back through Yoto's public API. Local -files are settings and caches only. - -Most of the interesting logic is local and offline: grouping and ordering files, cleaning titles, and -matching each title to an icon with trigram similarity. Claude is an optional extra in two places: the -user can ask Claude for icon keywords in the icon picker, and Claude Desktop can drive OpenMyo through -the Model Context Protocol (MCP). - -## System context - -```mermaid ---- -title: System context diagram for OpenMyo ---- -flowchart TB - user["Card maker
[Person]
A parent or teacher who makes
Yoto MYO cards"]:::person - claudeDesktop["Claude Desktop
[Software system, external, optional]
Chat app that can call
OpenMyo's tools"]:::ext - openmyo["OpenMyo
[Software system]
Bulk-creates and tidies
MYO playlists"]:::system - yoto["Yoto platform
[Software system, external]
Sign-in, card storage, audio
transcoding, icon library"]:::ext - yotoicons["yotoicons.com
[Software system, external, optional]
Community icon library"]:::ext - anthropic["Anthropic API
[Software system, external, optional]
Claude models"]:::ext - - user -->|"Imports audio folders,
edits playlists, picks icons"| openmyo - user -->|"Asks for title and
icon changes"| claudeDesktop - claudeDesktop -->|"Calls tools to read
and change playlists"| openmyo - openmyo -->|"Signs in; reads and saves cards;
uploads audio and images"| yoto - openmyo -->|"Downloads the icon listing;
imports chosen icons"| yotoicons - openmyo -->|"Asks for icon keywords
for one track title"| anthropic - - subgraph key["Key"] - direction LR - k1["Person"]:::person - k2["OpenMyo"]:::system - k3["External system"]:::ext - end - - classDef person fill:#08427b,stroke:#052e56,color:#fff - classDef system fill:#1168bd,stroke:#0b4884,color:#fff - classDef ext fill:#999999,stroke:#6b6b6b,color:#fff -``` - -## Containers - -```mermaid ---- -title: Container diagram for OpenMyo ---- -flowchart LR - user["Card maker
[Person]"]:::person - claudeDesktop["Claude Desktop
[Software system, external]"]:::ext - - subgraph openmyo["OpenMyo"] - app["Desktop app
[Container: .NET 10, Avalonia]
Library, editor, import
and settings screens"]:::container - connector["Claude Desktop connector
[Container: .NET 10, same executable
started with --mcp]
MCP server, no window"]:::container - data[("Data folder
[Container: files]
settings.json, token lock file,
encrypted secrets on Windows")]:::container - cache[("Cache folder
[Container: files]
Card JSON, icon lists,
yotoicons catalog, images")]:::container - end - - subgraph computer["User's computer"] - files["Audio files
[Folders on disk]"]:::ext - browser["System browser
[Software system, external]"]:::ext - secrets["OS secret store
[Software system, external]
macOS Keychain or
Windows DPAPI"]:::ext - end - - subgraph internet["Internet"] - yoto["Yoto platform
[Software system, external]
login.yotoplay.com, api.yotoplay.com,
upload storage"]:::ext - yotoicons["yotoicons.com
[Software system, external]"]:::ext - anthropic["Anthropic API
[Software system, external]"]:::ext - end - - user -->|"Imports, edits,
picks icons"| app - claudeDesktop -->|"Starts process; calls tools
[JSON-RPC over stdio]"| connector - app -->|"Reads tags, artwork
and audio"| files - app -->|"Opens Yoto sign-in page;
receives redirect
[HTTP, 127.0.0.1:8787]"| browser - app & connector -->|"Reads and writes
refresh token, API key"| secrets - app & connector -->|"Reads settings;
takes token lock"| data - app & connector -->|"Reads and writes
cached data"| cache - app & connector -->|"Tokens, cards, media, icons
[HTTPS, JSON]"| yoto - app & connector -->|"Listing pages, icon PNGs
[HTTPS]"| yotoicons - app -->|"Icon keyword request
[HTTPS, JSON]"| anthropic - - subgraph key["Key"] - direction LR - k1["Person"]:::person - k2["Container"]:::container - k3[("Data store")]:::container - k4["External system"]:::ext - end - - classDef person fill:#08427b,stroke:#052e56,color:#fff - classDef container fill:#438dd5,stroke:#2e6295,color:#fff - classDef ext fill:#999999,stroke:#6b6b6b,color:#fff -``` - -The desktop app and the connector are the same executable ([`Program`](../src/OpenMyo.App/Program.cs) -chooses the mode from the `--mcp` argument) and build the same services. They can run at the same time. -They never talk to each other directly; they share the secret store, the data and cache folders, and a -lock file that stops both refreshing the Yoto token at once. - -All communication is request and response. The one slow step is on Yoto's side: after an upload, Yoto -transcodes the audio in the background and OpenMyo polls until it is done. - -| Data | Location | -|---|---| -| Data folder | `~/Library/Application Support/OpenMyo` (macOS), `%LOCALAPPDATA%\OpenMyo` (Windows) | -| Cache folder | `~/Library/Caches/OpenMyo` (macOS), `%LOCALAPPDATA%\OpenMyo\Cache` (Windows); safe to delete | - -## Code map - -The solution is layered. `OpenMyo.Core` holds the domain and the algorithms; every other project either -implements a Core interface or uses Core. - -```text -App ──► Core, Yoto, Claude, Mcp, Infrastructure -Yoto, Claude, Mcp, Infrastructure ──► Core -Core ──► nothing in the solution -``` - -Folders are organised by feature, not by type, and a feature keeps the same folder name in every project -that has it: `Icons` exists in Core, Yoto and Mcp. The App groups its folders by screen instead (see -[`OpenMyo.App`](#openmyoapp)). - -### [`OpenMyo.Core`](../src/OpenMyo.Core) - -- [`Playlists/`](../src/OpenMyo.Core/Playlists): the domain records [`Playlist`](../src/OpenMyo.Core/Playlists/Playlist.cs), [`Chapter`](../src/OpenMyo.Core/Playlists/Chapter.cs), [`Track`](../src/OpenMyo.Core/Playlists/Track.cs) and [`PlaylistSummary`](../src/OpenMyo.Core/Playlists/PlaylistSummary.cs). All immutable. -- [`Abstractions/`](../src/OpenMyo.Core/Abstractions): the interfaces outer projects implement, such as [`IPlaylistRepository`](../src/OpenMyo.Core/Abstractions/IPlaylistRepository.cs), - [`IMediaUploader`](../src/OpenMyo.Core/Abstractions/IMediaUploader.cs), [`IIconCatalog`](../src/OpenMyo.Core/Abstractions/IIconCatalog.cs), [`ISecretStore`](../src/OpenMyo.Core/Abstractions/ISecretStore.cs), [`ISettingsStore`](../src/OpenMyo.Core/Abstractions/ISettingsStore.cs) and [`IYotoSession`](../src/OpenMyo.Core/Abstractions/IYotoSession.cs). -- [`Import/`](../src/OpenMyo.Core/Import): files to playlist drafts. [`ImportGrouper`](../src/OpenMyo.Core/Import/ImportGrouper.cs) decides which files form a playlist, - [`TrackOrderer`](../src/OpenMyo.Core/Import/TrackOrderer.cs) orders them, [`ArtworkLocator`](../src/OpenMyo.Core/Import/ArtworkLocator.cs) finds covers and icon art, [`DraftBuilder`](../src/OpenMyo.Core/Import/DraftBuilder.cs) runs the steps. -- [`Feeds/`](../src/OpenMyo.Core/Feeds): podcast RSS import. [`FeedParser`](../src/OpenMyo.Core/Feeds/FeedParser.cs) reads a feed for preview, - [`FeedImporter`](../src/OpenMyo.Core/Feeds/FeedImporter.cs) downloads the chosen episodes and artwork through [`IFeedClient`](../src/OpenMyo.Core/Abstractions/IFeedClient.cs) into a temporary cache folder and returns a `PlaylistDraft`. -- [`Text/`](../src/OpenMyo.Core/Text): text rules shared by import and icon matching. [`TitleCleaner`](../src/OpenMyo.Core/Text/TitleCleaner.cs), [`TextNormalizer`](../src/OpenMyo.Core/Text/TextNormalizer.cs), - [`Trigrams`](../src/OpenMyo.Core/Text/Trigrams.cs), [`IconQuery`](../src/OpenMyo.Core/Text/IconQuery.cs), and the word lists [`Synonyms.txt`](../src/OpenMyo.Core/Text/Synonyms.txt) and [`WeakWords.txt`](../src/OpenMyo.Core/Text/WeakWords.txt). -- [`Icons/`](../src/OpenMyo.Core/Icons): icon matching. [`IconIndex`](../src/OpenMyo.Core/Icons/IconIndex.cs) and [`IconScorer`](../src/OpenMyo.Core/Icons/IconScorer.cs) search and score, [`IconIndexProvider`](../src/OpenMyo.Core/Icons/IconIndexProvider.cs) builds the - shared index, [`IconSuggester`](../src/OpenMyo.Core/Icons/IconSuggester.cs) and [`IconAutoAssigner`](../src/OpenMyo.Core/Icons/IconAutoAssigner.cs) pick icons, [`NumberIconMaker`](../src/OpenMyo.Core/Icons/NumberIconMaker.cs) draws number icons, - [`AiIconSearch`](../src/OpenMyo.Core/Icons/AiIconSearch.cs) adds Claude keywords. -- [`CommunityIcons/`](../src/OpenMyo.Core/CommunityIcons): an offline copy of yotoicons.com. [`CommunityCatalogHarvester`](../src/OpenMyo.Core/CommunityIcons/CommunityCatalogHarvester.cs) downloads it, - [`CommunityCatalogProvider`](../src/OpenMyo.Core/CommunityIcons/CommunityCatalogProvider.cs) caches it, [`CommunityIconImporter`](../src/OpenMyo.Core/CommunityIcons/CommunityIconImporter.cs) copies a chosen icon to the user's account. -- [`Publishing/`](../src/OpenMyo.Core/Publishing): [`PlaylistPublisher`](../src/OpenMyo.Core/Publishing/PlaylistPublisher.cs) uploads media and creates or extends playlists. -- [`Playback/`](../src/OpenMyo.Core/Playback): [`PlaybackLists`](../src/OpenMyo.Core/Playback/PlaybackLists.cs) turns a playlist (with signed stream URLs) or an import draft into a - [`PlaybackList`](../src/OpenMyo.Core/Playback/PlaybackList.cs) for the player bar; the engine sits behind [`IAudioPlayer`](../src/OpenMyo.Core/Abstractions/IAudioPlayer.cs). -- [`Library/`](../src/OpenMyo.Core/Library): [`PlaylistHealth`](../src/OpenMyo.Core/Library/PlaylistHealth.cs) flags playlists with no tracks, missing icons or no cover. - -### [`OpenMyo.Yoto`](../src/OpenMyo.Yoto) - -- [`Http/`](../src/OpenMyo.Yoto/Http): named `HttpClient`s and [`RetryHandler`](../src/OpenMyo.Yoto/Http/RetryHandler.cs). -- [`Auth/`](../src/OpenMyo.Yoto/Auth): sign-in and tokens. [`YotoSession`](../src/OpenMyo.Yoto/Auth/YotoSession.cs) owns the tokens, [`LoopbackAuthorizer`](../src/OpenMyo.Yoto/Auth/LoopbackAuthorizer.cs) catches the browser - redirect, [`YotoAuthHandler`](../src/OpenMyo.Yoto/Auth/YotoAuthHandler.cs) adds the bearer token, [`RefreshLock`](../src/OpenMyo.Yoto/Auth/RefreshLock.cs) serialises refreshes across processes. -- [`Content/`](../src/OpenMyo.Yoto/Content): cards. [`YotoPlaylistRepository`](../src/OpenMyo.Yoto/Content/YotoPlaylistRepository.cs) implements [`IPlaylistRepository`](../src/OpenMyo.Core/Abstractions/IPlaylistRepository.cs), [`CardMapper`](../src/OpenMyo.Yoto/Content/CardMapper.cs) reads card - JSON, [`CardComposer`](../src/OpenMyo.Yoto/Content/CardComposer.cs) and [`ChapterComposer`](../src/OpenMyo.Yoto/Content/ChapterComposer.cs) write it, [`CardCache`](../src/OpenMyo.Yoto/Content/CardCache.cs) keeps the last copy of each card, - [`YotoTrackStreams`](../src/OpenMyo.Yoto/Content/YotoTrackStreams.cs) asks for signed, playable track URLs (`playable=true&signingType=s3`) and never caches them. -- [`Media/`](../src/OpenMyo.Yoto/Media): [`YotoMediaUploader`](../src/OpenMyo.Yoto/Media/YotoMediaUploader.cs) uploads audio, covers and icons. -- [`Icons/`](../src/OpenMyo.Yoto/Icons): [`YotoIconCatalog`](../src/OpenMyo.Yoto/Icons/YotoIconCatalog.cs) lists Yoto's public icons and the user's own. -- [`CommunityIcons/`](../src/OpenMyo.Yoto/CommunityIcons): [`YotoIconsClient`](../src/OpenMyo.Yoto/CommunityIcons/YotoIconsClient.cs) reads yotoicons.com. -- [`Json/`](../src/OpenMyo.Yoto/Json): response DTOs and the source-generated [`YotoJsonContext`](../src/OpenMyo.Yoto/Json/YotoJsonContext.cs). - -### [`OpenMyo.Claude`](../src/OpenMyo.Claude) - -[`ClaudeKeywordGenerator`](../src/OpenMyo.Claude/ClaudeKeywordGenerator.cs) implements [`IIconKeywordGenerator`](../src/OpenMyo.Core/Icons/IIconKeywordGenerator.cs): one track title in, a few icon keywords out. -[`KeywordPrompt`](../src/OpenMyo.Claude/KeywordPrompt.cs) holds the prompt and output schema. - -### [`OpenMyo.Mcp`](../src/OpenMyo.Mcp) - -The connector's tools. [`McpEntry`](../src/OpenMyo.Mcp/McpEntry.cs) starts the server, [`ToolRegistry`](../src/OpenMyo.Mcp/Support/ToolRegistry.cs) finds every `[McpServerTool]` method. -Tools live in [`Playlists/`](../src/OpenMyo.Mcp/Playlists) and [`Icons/`](../src/OpenMyo.Mcp/Icons); shared helpers such as [`PlaylistLookup`](../src/OpenMyo.Mcp/Support/PlaylistLookup.cs) and [`ToolGuard`](../src/OpenMyo.Mcp/Support/ToolGuard.cs) live in -[`Support/`](../src/OpenMyo.Mcp/Support). - -### [`OpenMyo.Infrastructure`](../src/OpenMyo.Infrastructure) - -Implementations that touch the local machine: [`TagLibAudioMetadataReader`](../src/OpenMyo.Infrastructure/Audio/TagLibAudioMetadataReader.cs) and the LibVLC-based -[`VlcAudioPlayer`](../src/OpenMyo.Infrastructure/Audio/VlcAudioPlayer.cs) ([`Audio/`](../src/OpenMyo.Infrastructure/Audio)), the secret stores -and [`SecretStoreFactory`](../src/OpenMyo.Infrastructure/Secrets/SecretStoreFactory.cs) ([`Secrets/`](../src/OpenMyo.Infrastructure/Secrets)), [`JsonSettingsStore`](../src/OpenMyo.Infrastructure/Settings/JsonSettingsStore.cs) ([`Settings/`](../src/OpenMyo.Infrastructure/Settings)), [`AppPaths`](../src/OpenMyo.Infrastructure/Paths/AppPaths.cs) and [`AtomicFile`](../src/OpenMyo.Infrastructure/Paths/AtomicFile.cs) -([`Paths/`](../src/OpenMyo.Infrastructure/Paths)), the Claude Desktop config writer ([`ClaudeDesktop/`](../src/OpenMyo.Infrastructure/ClaudeDesktop)), and -[`HttpFeedClient`](../src/OpenMyo.Infrastructure/Feeds/HttpFeedClient.cs), which fetches podcast feeds and downloads episodes to disk ([`Feeds/`](../src/OpenMyo.Infrastructure/Feeds)). - -### [`OpenMyo.App`](../src/OpenMyo.App) - -The Avalonia UI. - -- [`Composition/`](../src/OpenMyo.App/Composition): [`ServiceRegistration`](../src/OpenMyo.App/Composition/ServiceRegistration.cs) is the composition root, - [`ScreenLinks`](../src/OpenMyo.App/Composition/ScreenLinks.cs) holds every link between pages (sign-in, refresh after import, icon index updates), - [`McpMode`](../src/OpenMyo.App/Composition/McpMode.cs) runs the connector. -- [`Screens/`](../src/OpenMyo.App/Screens): one folder per feature (`Shell`, `Library`, `Editor`, `Import`, `IconPicker`, `Settings`), - each holding its views beside their view models. [`MainViewModel`](../src/OpenMyo.App/Screens/Shell/MainViewModel.cs) is the shell. -- [`Services/`](../src/OpenMyo.App/Services): app-only helpers such as [`IconBitmapLoader`](../src/OpenMyo.App/Services/IconBitmapLoader.cs), the file picker and - [`BackgroundWork`](../src/OpenMyo.App/Services/BackgroundWork.cs). -- [`Controls/`](../src/OpenMyo.App/Controls) and [`Styles/`](../src/OpenMyo.App/Styles): reusable controls and the theme. - -[`src/OpenMyo.App/README.md`](../src/OpenMyo.App/README.md) has the file map, which view uses which view model, and how they talk. - -### Tests and tools - -[`tests/`](../tests) has one project per library, mirroring its folders. Core tests use the fakes in -`OpenMyo.Core.Tests/Fakes`; Yoto tests stub HTTP with [`StubHttpHandler`](../tests/OpenMyo.Yoto.Tests/Support/StubHttpHandler.cs). -[`tools/OpenMyo.Snapshots`](../tools/OpenMyo.Snapshots) renders the screens to PNG with sample data, so UI changes can be checked without a Yoto account. - -## Invariants - -- **Core references no other OpenMyo project** and no UI, HTTP or platform package. -- **Only `OpenMyo.App` knows concrete types.** Libraries register their services through one - `AddXxx()` method each. -- **Domain records are never mutated.** Every edit creates a new record with `with { … }`. -- **A save never rebuilds a card.** It patches the last card fetched from Yoto, so fields OpenMyo does not - model survive. -- **The refresh token is only read or used inside both the in-process gate and [`RefreshLock`](../src/OpenMyo.Yoto/Auth/RefreshLock.cs).** Yoto - refresh tokens are single-use; two concurrent refreshes sign the user out. -- **The bearer token is only sent by the `yoto-api` client.** Upload storage, yotoicons.com and Anthropic - never see it. -- **Claude never chooses an icon.** It returns keywords that are matched locally, and icon matching works - without an Anthropic key. -- **In connector mode nothing but MCP messages is written to stdout**, so Avalonia never starts. -- **Services throw; only the UI boundary catches everything.** The catch-alls are - [`OperationViewModel.RunAsync`](../src/OpenMyo.App/Screens/OperationViewModel.cs) (user actions), - [`BackgroundWork.Forget`](../src/OpenMyo.App/Services/BackgroundWork.cs) (work nobody awaits) and - [`IconBitmapLoader`](../src/OpenMyo.App/Services/IconBitmapLoader.cs) (pictures). Each one logs the failure. -- **View models never reference each other sideways.** A parent owns its children; children raise events; - links between pages live in [`ScreenLinks`](../src/OpenMyo.App/Composition/ScreenLinks.cs). -- **Secrets never appear in settings, logs or URLs.** - -## Cross-cutting concerns - -**Async and cancellation.** All I/O is async and takes a `CancellationToken`. Long operations in the UI -run through [`OperationViewModel.RunAsync`](../src/OpenMyo.App/Screens/OperationViewModel.cs), which owns busy state, the Cancel button and error display. -Work that is started but not awaited (a search as the user types, a refresh after an event) goes through -`Forget(logger, description)` so its failure is logged rather than lost. - -**Concurrency.** Parallel work is always bounded: uploads by the `MaxParallelUploads` setting (1–8), -library detail loads at 6, yotoicons.com pages and icon imports at 4. Results are written by index, so -parallelism never changes order. Shared loads (icon catalog, icon index, community catalog) are -singletons that hand every caller the same in-flight `Task`. - -**Errors.** Yoto responses that fail become [`YotoApiException`](../src/OpenMyo.Yoto/Http/YotoApiException.cs). The `yoto-api` client retries 429 and 503 -up to three times and refreshes the token once on 401. Optional sources (yotoicons.com, Anthropic) fail -soft: matching carries on without them. At the UI boundary every failure is logged through `ILogger` with -its full exception, and the user sees a plain sentence instead: "Couldn't reach the server" for network -errors, a permissions or file hint for disk errors, otherwise the exception's own message. - -**Caching.** - -| Data | Where | Lifetime | -|---|---|---| -| Card JSON | Memory and `cache/cards/` | Reused while the card's `updatedAt` is unchanged | -| Yoto public icon list | `cache/icons/public.json` | 7 days; a stale copy is used offline | -| User's own icon list | Memory | Until the next icon upload | -| Icon search index | Memory | Rebuilt after an icon upload or a library load | -| yotoicons.com catalog | `cache/yotoicons/catalog.json` | 7 days; an incomplete download is retried next launch | -| Claude keywords | Memory | Per title, for the session | -| Icon and cover images | Memory and `cache/images/` | Until evicted | - -**Security.** OAuth uses Authorization Code with PKCE on a loopback redirect and a checked `state`; each -user registers their own public client, so the binary holds no client secret. Tokens and the API key live -in the OS secret store. Card ids, media ids and title lengths are validated before they reach a URL or a -save. Claude receives track titles and the icon vocabulary only. - -**UI (Avalonia).** The screens use Avalonia 11 with MVVM. Views bind to view models with compiled -bindings (`AvaloniaUseCompiledBindingsByDefault` and `x:DataType`), so a wrong binding path fails the build. -Buttons and menu items run `ICommand`s that CommunityToolkit.Mvvm generates from `[RelayCommand]` methods; -`Click` handlers are only for view-only work such as focus and drag-and-drop. Avalonia draws its own -controls, so a screen looks and behaves the same on macOS and Windows. Only the desktop head -(`Avalonia.Desktop`) is built today; see [Commands](design/app.md#commands) and -[Other platforms](design/app.md#other-platforms). - -**Testing.** Tests never touch the network or a real keychain. Core logic is tested with fakes of the -Core interfaces; the Yoto client is tested against stubbed HTTP responses. - -## Glossary - -| Term | Meaning | -|---|---| -| Card | A Yoto playlist, stored by Yoto as one JSON document | -| Chapter | One entry in a card; what the user sees as a track. Usually holds one track | -| MYO | Make Your Own: Yoto's user-created cards | -| Media id | 43-character id of an uploaded image or icon, written as `yoto:#` | -| MCP | Model Context Protocol, how Claude Desktop calls OpenMyo's tools | -| PKCE | Proof Key for Code Exchange, the OAuth flow for apps without a client secret | -| DPAPI | Windows Data Protection API, used to encrypt secrets on Windows | -| Trigram | A three-character slice of a word, used for fuzzy matching | - -## Further documents - -- [The Yoto client](design/yoto-client.md): the card model, HTTP pipeline, sign-in and tokens, reading and - saving cards, uploads. -- [Bulk import](design/import.md): grouping, ordering, title cleaning, artwork, publishing. -- [Icon matching](design/icon-matching.md): normalising words, trigram scoring, suggestions, number icons, - Claude keywords, community icons. -- [The desktop app and the Claude Desktop connector](design/app.md): start-up, navigation, commands, library, - editor, connector, other platforms. -- [Track search and Yoto players](design/players.md): search matching, the output picker, MQTT player - control, connection lifecycle. -- [Design decisions](design/decisions.md): the main choices, why they were made, and what they give users. -- [How-to guides](how-to.md): adding endpoints, card fields, logic, settings, MCP tools and screens. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md deleted file mode 100644 index fad5c65..0000000 --- a/docs/USER_GUIDE.md +++ /dev/null @@ -1,102 +0,0 @@ -# OpenMyo user guide - -How to use OpenMyo once it is running. To build and run it, see the [README](../README.md). - -## What it does - -Bulk import. Choose or drag in folders or audio files and each folder becomes a playlist. Track -numbers, underscores, "(Official Audio)"-style noise and repeated artist prefixes are removed from -titles. Tracks are ordered by disc and track tags, then leading numbers, then name. Cover art comes from -an image in the folder (`cover.jpg`, `folder.jpg`, ...) or from art embedded in the audio, and a track -gets an icon from an image with the same base name as its audio file. - -Import from a podcast feed. On the Import screen choose **From Feed…** (or paste a feed link anywhere on -the screen), then **Preview** to list the episodes. The latest 100 are ticked, since a playlist holds up -to 100 tracks. Narrow the list with **Length** (from / to, in minutes), **Exclude titles with** (for -example `trailer, bonus`) and **Only titles with**; hidden episodes are never downloaded. **Order** sets -oldest or newest first, both in the list and on the card. Change the ticks, then **Download & Add**. The -episodes download into a temporary folder and appear as a draft named after the show, with the show's -artwork as its cover. Review it like any other import and choose **Create Playlists**. The -downloaded files are deleted once the playlist is created or the draft is discarded. - -Library. Your playlists as a list or a grid of covers, with filters for empty playlists, missing icons -and missing covers. Select several to match their icons or delete them together. - -Search. The library's search field finds playlists by title and tracks by title, across every playlist. -Every word you type must appear, in any order, ignoring capitals and accents ("gruff child" finds "The -Gruffalo's Child"). Matching tracks are listed under their playlist with the matched words highlighted; -click one to open the playlist at that track, ready to play. - -Playlist editor. Rename tracks, drag to reorder, set the cover and pick icons. Hints such as "31 missing -icons" or "Tidy 8 titles" only appear when they apply, and each is one click. Select several tracks to -give them the same icon, number them or remove them. - -Playback. Hover a track in the playlist editor or on the Import screen and press ▶ to listen from that -track on; the rest of the playlist plays after it. The bar along the bottom of the window has play/pause, -previous, next, a position slider and volume, and keeps playing while you move between screens. The -keyboard's media keys and Cmd/Ctrl+Shift+Space also play and pause. Import previews play your local files -before anything is uploaded. - -Play on a Yoto player. While something plays, the speaker button in the bottom-right corner of the bar -lists **This computer** and your Yoto players (offline ones are greyed out). Choose an idle player and -what is playing here moves to it, at the same track and position; a player that is already playing -carries on undisturbed. Yoto players that are playing also show as a line each in the bar, with pause, -volume and **Control** (which makes that player the output without changing what it plays). Until you -switch back, every ▶ plays on that player, -and the bar shows its track, play/pause, next/previous, position and volume. OpenMyo always starts on -**This computer**, so opening it never plays out loud in another room. The first time after this feature -arrives, Yoto asks you to sign in once more to allow OpenMyo to control your players. - -Title clean-up. Each cleanup rule can be switched on or off, you can add your own find and replace, and -a preview shows the result before anything changes. Titles that follow a pattern on purpose, like -"[051] Episode", are left alone. - -Icon matching. Track titles are matched by trigram similarity against Yoto's public icons, the icons -already in your playlists and Yoto's number icons. If Yoto has nothing close, a strong match from -[yotoicons.com](https://yotoicons.com) is added to your icons. This doesn't use AI. - -Community icons. The icon picker also searches yotoicons.com, credits the artist and adds the icon you -choose to your Yoto account. The search runs against a local copy of the catalog (about 26,000 icons), -refreshed weekly. Images are only downloaded when shown. - -Search with AI (optional). With your own Anthropic API key, each icon picker gets a **Search with AI** -button. Claude only runs when you click it. It suggests a few words for that one title, and those are -matched against the local icon index. Answers are cached per title. - -Rename with AI (optional). In the playlist editor's **⋯** menu, **Rename Every Title with AI** asks Claude -for a clean title for every track (no track numbers, file-name leftovers or repeated album names). The new -titles show as unsaved edits: check them, then **Save**, or **Revert** to undo. Without an API key, a -connected Claude Desktop gets the request instead and saves straight to Yoto. - -Secrets are stored in the macOS Keychain or Windows DPAPI, never in settings files. - -## Claude setup (optional) - -Icon matching works without Claude. To add **Search with AI** to the icon picker, turn on -**AI Icon Search** in **Settings**, then paste an API key from the Anthropic console. The default model is `claude-opus-5-5` and can be changed there. The -key is stored in the Keychain / DPAPI. Claude never sees your audio, only track titles. - -## Use with Claude Desktop - -OpenMyo can act as an [MCP](https://modelcontextprotocol.io) server, so Claude Desktop can rename playlists -and tracks, pick icons, find tracks across your playlists and play them on a Yoto player ("play the -Gruffalo on the bedroom Yoto"). It uses your own Claude subscription; no API key is needed. - -Claude Desktop launches the OpenMyo app with `--mcp` and talks to it over stdio. The -server uses the Yoto session you already signed in with in OpenMyo, so sign in there first. In -**Settings**, **Connect to Claude Desktop** adds OpenMyo to Claude Desktop's configuration; restart Claude -Desktop afterwards. - -Tools: `list_playlists`, `get_playlist`, `rename_playlist`, `rename_tracks`, `search_icons` (Yoto, your uploads and -yotoicons.com), `set_track_icons`, `auto_match_icons` and `number_track_icons`. - -Example prompts: - -- "Pick icons for my Odyssey playlist." -- "Which tracks in Bedtime Stories have no icon? Find good ones for them." -- "Number the icons on my Counting Songs playlist." -- "Remove the 'Chapter N -' prefix from every track in The Hobbit." -- "Rename my Bedtime playlist to Bedtime Stories." - -Changes save straight to Yoto. Claude Desktop asks before each tool call, and each change reports the -previous titles or icons, so you can ask Claude to undo it. diff --git a/docs/contribute/architecture/cross-cutting-concerns.md b/docs/contribute/architecture/cross-cutting-concerns.md new file mode 100644 index 0000000..84ebdc7 --- /dev/null +++ b/docs/contribute/architecture/cross-cutting-concerns.md @@ -0,0 +1,67 @@ +--- +title: Cross-cutting concerns +description: Understand how OpenMyo handles async work, concurrency, errors, security, the Avalonia UI and testing across every project. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Cross-cutting concerns + +These conventions apply in every project. The mandatory rules are in [CODESTANDARDS.md](../../../CODESTANDARDS.md); this page explains the reasons. + +## Async and cancellation + +All I/O is async and takes a `CancellationToken`. Long operations in the UI +run through [`OperationViewModel.RunAsync`](../../../src/OpenMyo.App/Screens/OperationViewModel.cs), which owns busy state, the Cancel button and error display. +Work that is started but not awaited (a search as the user types, a refresh after an event) goes through +`Forget(logger, description)` so its failure is logged rather than lost. + +## Concurrency + +Parallel work is always bounded: uploads by the `MaxParallelUploads` setting, and library loads, yotoicons.com +pages and icon imports by fixed small limits. Results are written by index, so +parallelism never changes order. Shared loads (icon catalog, icon index, community catalog) are +singletons that hand every caller the same in-flight `Task`. + +## Errors + +Yoto responses that fail become [`YotoApiException`](../../../src/OpenMyo.Yoto/Http/YotoApiException.cs). The `yoto-api` client retries 429 and 503 +a few times and refreshes the token once on 401. Optional sources (yotoicons.com, Anthropic) fail +soft: matching carries on without them. At the UI boundary every failure is logged through `ILogger` with +its full exception, and the user sees a plain sentence instead: "Couldn't reach the server" for network +errors, a permissions or file hint for disk errors, otherwise the exception's own message. + +## Security + +OAuth uses Authorization Code with PKCE on a loopback redirect and a checked `state`; each +user registers their own public client, so the binary holds no client secret. Tokens and the API key live +in the OS secret store. Card ids, media ids and title lengths are validated before they reach a URL or a +save. Claude receives track titles and the icon vocabulary only. + +## UI (Avalonia) + +The screens use Avalonia 11 with MVVM. Views bind to view models with compiled +bindings (`AvaloniaUseCompiledBindingsByDefault` and `x:DataType`), so a wrong binding path fails the build. +Buttons and menu items run `ICommand`s that CommunityToolkit.Mvvm generates from `[RelayCommand]` methods; +`Click` handlers are only for view-only work such as focus and drag-and-drop. Avalonia draws its own +controls, so a screen looks and behaves the same on macOS and Windows. See [Commands](../concepts/navigation-and-commands.md#commands). + +## Caching + +OpenMyo caches card JSON, Yoto's public icon list, the yotoicons.com catalog and icon and cover images on +disk, and keeps the user's own icons, the icon search index and Claude keywords in memory. Cards are reused +while their `updatedAt` is unchanged (see [Read and save cards](../concepts/read-and-save-cards.md)). The +cache folder is disposable: deleting it only costs a re-download. For where the folders are, see +[Data locations](../../user/reference/data-locations.md). + +## Testing + +Tests never touch the network or a real keychain. Core logic is tested with fakes of the +Core interfaces; the Yoto client is tested against stubbed HTTP responses. + +## Related content + +- [Invariants](invariants.md) +- [Data locations (user reference)](../../user/reference/data-locations.md) +- [Yoto HTTP pipeline](../concepts/yoto-http-pipeline.md) +- [Sign-in and tokens](../concepts/sign-in-and-tokens.md) diff --git a/docs/contribute/architecture/invariants.md b/docs/contribute/architecture/invariants.md new file mode 100644 index 0000000..e358f75 --- /dev/null +++ b/docs/contribute/architecture/invariants.md @@ -0,0 +1,39 @@ +--- +title: Architecture invariants +description: The rules about dependencies, card saving, tokens, Claude and error handling that every change to OpenMyo must keep true. +ms.topic: reference +ms.date: 11/16/2026 +--- + +# Architecture invariants + +Check your change against these rules before you open a pull request. + +- **Core references no other OpenMyo project** and no UI, HTTP or platform package. +- **Only `OpenMyo.App` knows concrete types.** Libraries register their services through one + `AddXxx()` method each. +- **Domain records are never mutated.** Every edit creates a new record with `with { … }`. +- **A save never rebuilds a card.** It patches the last card fetched from Yoto, so fields OpenMyo does not + model survive. +- **The refresh token is only read or used inside both the in-process gate and [`RefreshLock`](../../../src/OpenMyo.Yoto/Auth/RefreshLock.cs).** Yoto + refresh tokens are single-use; two concurrent refreshes sign the user out. +- **The bearer token is only sent by the `yoto-api` client.** Upload storage, yotoicons.com and Anthropic + never see it. +- **Claude never chooses an icon.** It returns keywords that are matched locally, and icon matching works + without an Anthropic key. +- **In connector mode nothing but MCP messages is written to stdout**, so Avalonia never starts. +- **Services throw; only the UI boundary catches everything.** The catch-alls are + [`OperationViewModel.RunAsync`](../../../src/OpenMyo.App/Screens/OperationViewModel.cs) (user actions), + [`BackgroundWork.Forget`](../../../src/OpenMyo.App/Services/BackgroundWork.cs) (work nobody awaits) and + [`IconBitmapLoader`](../../../src/OpenMyo.App/Services/IconBitmapLoader.cs) (pictures). Each one logs the failure. +- **View models never reference each other sideways.** A parent owns its children; children raise events; + links between pages live in [`ScreenLinks`](../../../src/OpenMyo.App/Composition/ScreenLinks.cs). +- **Secrets never appear in settings, logs or URLs.** + +## Related content + +- [Architecture overview](overview.md) +- [Cross-cutting concerns](cross-cutting-concerns.md) +- [Design decisions](../reference/design-decisions.md) +- [Read and save cards](../concepts/read-and-save-cards.md) +- [Sign-in and tokens](../concepts/sign-in-and-tokens.md) diff --git a/docs/contribute/architecture/overview.md b/docs/contribute/architecture/overview.md new file mode 100644 index 0000000..e74328d --- /dev/null +++ b/docs/contribute/architecture/overview.md @@ -0,0 +1,154 @@ +--- +title: Architecture overview +description: Understand what OpenMyo is, how its desktop app and Claude Desktop connector fit together, and which external systems it talks to. +ms.topic: overview +ms.date: 11/16/2026 +--- + +# Architecture overview + +This article gives you the bird's-eye view of OpenMyo: what it does, which systems it talks to, and how the executable is split into containers. Read it when you start work in the repo or need to decide where a change belongs. + +## Bird's eye view + +OpenMyo is a desktop app for macOS and Windows that manages Yoto "Make Your Own" (MYO) playlists. It +turns folders of audio files into playlists on the user's Yoto account, and tidies existing playlists: +titles, track order, covers and the 16×16 pixel icon shown for each track. + +OpenMyo has no server and keeps no playlists of its own. Every playlist lives on Yoto as a JSON document +called a **card**. OpenMyo reads cards, changes them, and saves them back through Yoto's public API. Local +files are settings and caches only. + +Most of the interesting logic is local and offline: grouping and ordering files, cleaning titles, and +matching each title to an icon with trigram similarity. Claude is an optional extra in two places: the +user can ask Claude for icon keywords in the icon picker, and Claude Desktop can drive OpenMyo through +the Model Context Protocol (MCP). + +## System context + +```mermaid +--- +title: System context diagram for OpenMyo +--- +flowchart TB + user["Card maker
[Person]
A parent or teacher who makes
Yoto MYO cards"]:::person + claudeDesktop["Claude Desktop
[Software system, external, optional]
Chat app that can call
OpenMyo's tools"]:::ext + openmyo["OpenMyo
[Software system]
Bulk-creates and tidies
MYO playlists"]:::system + yoto["Yoto platform
[Software system, external]
Sign-in, card storage, audio
transcoding, icon library"]:::ext + yotoicons["yotoicons.com
[Software system, external, optional]
Community icon library"]:::ext + anthropic["Anthropic API
[Software system, external, optional]
Claude models"]:::ext + + user -->|"Imports audio folders,
edits playlists, picks icons"| openmyo + user -->|"Asks for title and
icon changes"| claudeDesktop + claudeDesktop -->|"Calls tools to read
and change playlists"| openmyo + openmyo -->|"Signs in; reads and saves cards;
uploads audio and images"| yoto + openmyo -->|"Downloads the icon listing;
imports chosen icons"| yotoicons + openmyo -->|"Asks for icon keywords
for one track title"| anthropic + + subgraph key["Key"] + direction LR + k1["Person"]:::person + k2["OpenMyo"]:::system + k3["External system"]:::ext + end + + classDef person fill:#08427b,stroke:#052e56,color:#fff + classDef system fill:#1168bd,stroke:#0b4884,color:#fff + classDef ext fill:#999999,stroke:#6b6b6b,color:#fff +``` + +## Containers + +```mermaid +--- +title: Container diagram for OpenMyo +--- +flowchart LR + user["Card maker
[Person]"]:::person + claudeDesktop["Claude Desktop
[Software system, external]"]:::ext + + subgraph openmyo["OpenMyo"] + app["Desktop app
[Container: .NET 10, Avalonia]
Library, editor, import
and settings screens"]:::container + connector["Claude Desktop connector
[Container: .NET 10, same executable
started with --mcp]
MCP server, no window"]:::container + data[("Data folder
[Container: files]
settings.json, token lock file,
encrypted secrets on Windows")]:::container + cache[("Cache folder
[Container: files]
Card JSON, icon lists,
yotoicons catalog, images")]:::container + end + + subgraph computer["User's computer"] + files["Audio files
[Folders on disk]"]:::ext + browser["System browser
[Software system, external]"]:::ext + secrets["OS secret store
[Software system, external]
macOS Keychain or
Windows DPAPI"]:::ext + end + + subgraph internet["Internet"] + yoto["Yoto platform
[Software system, external]
login.yotoplay.com, api.yotoplay.com,
upload storage"]:::ext + yotoicons["yotoicons.com
[Software system, external]"]:::ext + anthropic["Anthropic API
[Software system, external]"]:::ext + end + + user -->|"Imports, edits,
picks icons"| app + claudeDesktop -->|"Starts process; calls tools
[JSON-RPC over stdio]"| connector + app -->|"Reads tags, artwork
and audio"| files + app -->|"Opens Yoto sign-in page;
receives redirect
[HTTP, 127.0.0.1:8787]"| browser + app & connector -->|"Reads and writes
refresh token, API key"| secrets + app & connector -->|"Reads settings;
takes token lock"| data + app & connector -->|"Reads and writes
cached data"| cache + app & connector -->|"Tokens, cards, media, icons
[HTTPS, JSON]"| yoto + app & connector -->|"Listing pages, icon PNGs
[HTTPS]"| yotoicons + app -->|"Icon keyword request
[HTTPS, JSON]"| anthropic + + subgraph key["Key"] + direction LR + k1["Person"]:::person + k2["Container"]:::container + k3[("Data store")]:::container + k4["External system"]:::ext + end + + classDef person fill:#08427b,stroke:#052e56,color:#fff + classDef container fill:#438dd5,stroke:#2e6295,color:#fff + classDef ext fill:#999999,stroke:#6b6b6b,color:#fff +``` + +The desktop app and the connector are the same executable ([`Program`](../../../src/OpenMyo.App/Program.cs) +chooses the mode from the `--mcp` argument) and build the same services. They can run at the same time. +They never talk to each other directly; they share the secret store, the data and cache folders, and a +lock file that stops both refreshing the Yoto token at once. + +All communication is request and response. The one slow step is on Yoto's side: after an upload, Yoto +transcodes the audio in the background and OpenMyo polls until it is done. + +## Projects + +The solution is layered. `OpenMyo.Core` holds the domain and the algorithms; every other project either +implements a Core interface or uses Core. + +```text +App ──► Core, Yoto, Claude, Mcp, Infrastructure +Yoto, Claude, Mcp, Infrastructure ──► Core +Core ──► nothing in the solution +``` + +Folders are organised by feature, not by type, and a feature keeps the same folder name in every project +that has it. The App groups its folders by screen instead. + +| Project | Owns | +|---|---| +| [`OpenMyo.Core`](../../../src/OpenMyo.Core) | Domain records, the interfaces other projects implement, import, icon matching and other pure logic | +| [`OpenMyo.Yoto`](../../../src/OpenMyo.Yoto) | Everything that talks to Yoto and yotoicons.com: sign-in, HTTP pipeline, cards, media, icons, player control | +| [`OpenMyo.Claude`](../../../src/OpenMyo.Claude) | The Anthropic API calls and their prompts | +| [`OpenMyo.Mcp`](../../../src/OpenMyo.Mcp) | The Claude Desktop connector's MCP server and tools | +| [`OpenMyo.Infrastructure`](../../../src/OpenMyo.Infrastructure) | Local-machine implementations: audio, secret stores, settings, paths, feeds | +| [`OpenMyo.App`](../../../src/OpenMyo.App) | The Avalonia UI and the composition root; see its [README](../../../src/OpenMyo.App/README.md) | + +[`tests/`](../../../tests) has one project per library, mirroring its folders. +[`tools/OpenMyo.Snapshots`](../../../tools/OpenMyo.Snapshots) renders screens to PNG with sample data. + +For the data and cache folder locations, see [Data locations](../../user/reference/data-locations.md). + +## Related content + +- [Invariants](invariants.md) +- [Cross-cutting concerns](cross-cutting-concerns.md) +- [Design decisions](../reference/design-decisions.md) +- [Glossary](../reference/glossary.md) diff --git a/docs/contribute/concepts/ai-icon-search.md b/docs/contribute/concepts/ai-icon-search.md new file mode 100644 index 0000000..061bfa5 --- /dev/null +++ b/docs/contribute/concepts/ai-icon-search.md @@ -0,0 +1,25 @@ +--- +title: AI icon search +description: Understand how the optional Search with AI button asks Claude for drawable keywords that OpenMyo then matches locally. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# AI icon search + +**Search with AI** is the optional, click-only way to find icons with Claude. Claude never sees icon ids and +never chooses an icon. It only suggests a few *drawable keywords* for a title, which are then matched locally +like any other search (see [Icon matching](icon-matching.md)). + +- [`AiIconSearch`](../../../src/OpenMyo.Core/Icons/AiIconSearch.cs) runs only when the user clicks the button in + the icon picker, and caches answers per title for the session. +- The prompt includes the index vocabulary, so Claude picks words that actually exist on icons. The system + prompt is prompt-cached and the output is constrained to a JSON schema. The implementation is in `src/OpenMyo.Claude/`. +- The model comes from Settings. The API key comes from `ISecretStore`. +- If there is no key, or the call fails, matching carries on with trigrams only. + +## Related content + +- [Icon matching](icon-matching.md) +- [Community icons](community-icons.md) +- [Match icons](../../user/match-icons.md) diff --git a/docs/contribute/concepts/app-startup.md b/docs/contribute/concepts/app-startup.md new file mode 100644 index 0000000..00dcef4 --- /dev/null +++ b/docs/contribute/concepts/app-startup.md @@ -0,0 +1,49 @@ +--- +title: App start-up and composition +description: Understand how OpenMyo starts in window or connector mode, builds its services, restores the Yoto session and reports UI errors. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# App start-up and composition + +`OpenMyo.App` hosts both the Avalonia window and the windowless MCP connector that Claude Desktop starts. +Both build the same services, so a feature in Core is available to the screens and the tools alike. + +## Launch modes + +[`Program.Main`](../../../src/OpenMyo.App/Program.cs) picks one of two modes: + +- **Window mode** (normal): starts Avalonia and shows the main window. +- **Connector mode** (`--mcp`): builds the *same* services, silently restores the Yoto session, and serves + MCP over stdio. Avalonia never starts, and nothing else may write to stdout. See + [Claude Desktop connector](claude-desktop-connector.md). + +## Composition root + +[`ServiceRegistration.Build`](../../../src/OpenMyo.App/Composition/ServiceRegistration.cs) is the composition +root. It calls each project's `AddXxx()` and registers the view models. Two details: + +- Almost everything is a **singleton**. The caches and shared in-flight loads only work + because there is one instance per process. +- Every `HttpClient` gets a `User-Agent`, because Yoto's media CDN returns 403 without one. + +## What happens at launch + +`MainViewModel.InitializeAsync` loads settings, then tries to restore the Yoto session. If a stored refresh +token still works, the shell opens the library. If not, the app opens on Settings so the user can enter a +client id and sign in. See [Sign-in and tokens](sign-in-and-tokens.md). + +## How the UI handles work and errors + +Every screen view model derives from +[`OperationViewModel`](../../../src/OpenMyo.App/Screens/OperationViewModel.cs). Its `RunAsync(status, work)` +sets `IsBusy`, gives the work a `CancellationToken` wired to the Cancel button, and catches *all* +exceptions, showing the message in `Error`. This is the one deliberate catch-all in the codebase: +services below it throw, and the UI boundary reports. + +## Related content + +- [Navigation and commands](navigation-and-commands.md) +- [Claude Desktop connector](claude-desktop-connector.md) +- [Cross-cutting concerns](../architecture/cross-cutting-concerns.md) diff --git a/docs/contribute/concepts/card-model.md b/docs/contribute/concepts/card-model.md new file mode 100644 index 0000000..073a648 --- /dev/null +++ b/docs/contribute/concepts/card-model.md @@ -0,0 +1,53 @@ +--- +title: Card model +description: Understand how a Yoto Make Your Own card is structured and how OpenMyo maps it to immutable domain records. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Card model + +Everything OpenMyo does ends up as a change to a **card** on Yoto's `/content` API. + +## Structure of a card + +A Make Your Own card is one JSON document: + +```text +card +├─ cardId, title, updatedAt, … (plus fields OpenMyo does not model) +├─ metadata.cover.imageL cover image URL +└─ content.chapters[] what the player steps through + ├─ key "01", title, overlayLabel "1" + ├─ display.icon16x16 "yoto:#" the 16×16 pixel icon the player shows + └─ tracks[] + ├─ key "01", title + ├─ trackUrl "yoto:#" transcoded audio held by Yoto + └─ format, duration, fileSize, channels, display.icon16x16 +``` + +## Properties that shape the code + +- **A chapter is what the user sees as "a track".** MYO cards normally have one track per chapter. + OpenMyo creates exactly that shape, renaming a single-track chapter renames its track too, and setting an + icon sets it on the chapter *and* each of its tracks. +- **Icons are referenced by media id.** Yoto's public icons and the user's own uploads live in the same id + space, so assigning an icon is just writing `yoto:#`. +- **Audio is referenced by content hash.** Uploading a file gives back `yoto:#`. +- **Saving is whole-document.** `POST /content` with a `cardId` replaces the card. There is no + per-field PATCH, so OpenMyo saves by patching the last-fetched document (see [Read and save cards](read-and-save-cards.md)). +- **Titles are capped at 140 characters.** Yoto rejects the whole save for one over-long chapter title + without saying which. + +## Domain records + +The domain mirrors this as immutable records in `src/OpenMyo.Core/Playlists/`: `Playlist` → `Chapter` → +`Track`, plus `PlaylistSummary` for the cheap library listing. Every edit produces a new record +(`with { … }`); nothing mutates a playlist in place. + +## Related content + +- [Read and save cards](read-and-save-cards.md) +- [Yoto HTTP pipeline](yoto-http-pipeline.md) +- [Upload media](media-uploads.md) +- [Architecture overview](../architecture/overview.md) diff --git a/docs/contribute/concepts/claude-desktop-connector.md b/docs/contribute/concepts/claude-desktop-connector.md new file mode 100644 index 0000000..41697d3 --- /dev/null +++ b/docs/contribute/concepts/claude-desktop-connector.md @@ -0,0 +1,49 @@ +--- +title: Claude Desktop connector +description: Understand how OpenMyo runs as an MCP server for Claude Desktop, how tools are registered and guarded, and how write tools stay safe. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Claude Desktop connector + +Settings → Claude Desktop writes an entry into Claude Desktop's config that launches this same executable +with `--mcp`. Claude Desktop then starts OpenMyo as a background process and talks to it over stdin/stdout. +See [App start-up and composition](app-startup.md) for how connector mode boots. + +```mermaid +sequenceDiagram + participant D as Claude Desktop + participant M as Connector (stdio) + participant T as Tool class (from DI) + participant R as Playlist repository + participant Y as Yoto API + + D->>M: Start "OpenMyo --mcp" + D->>M: tools/call set_track_icons + M->>T: Resolve the method's class from DI + T->>T: Validate track range and icon ids + T->>R: Get, then one Save + R->>Y: GET / POST content + T-->>D: Result with previous icons (for undo) + Note over T,D: Not signed in or network error → plain-sentence MCP error +``` + +## How it works + +- [`McpEntry`](../../../src/OpenMyo.Mcp/McpEntry.cs) creates the server with fixed instructions describing the + intended workflow. +- The registry finds every `[McpServerTool]` method in the assembly and resolves its class from DI on each + call, so tools use the same singletons as the app. The tools live in `src/OpenMyo.Mcp/`. +- Tools that write **validate everything first** (track range, icon ids), then save once. They return the + previous titles or icons so Claude can undo. +- A guard turns "not signed in" and network errors into plain MCP errors instead of stack traces. +- Sign-in is shared with the app through the secret store, and refreshes are coordinated across processes + (see [Sign-in and tokens](sign-in-and-tokens.md)). The connector never opens a browser: if there is no + session, tools say "open OpenMyo and sign in". + +## Related content + +- [Add a Claude Desktop tool](../how-to/add-claude-desktop-tool.md) +- [Sign-in and tokens](sign-in-and-tokens.md) +- [Use OpenMyo with Claude Desktop](../../user/use-with-claude-desktop.md) diff --git a/docs/contribute/concepts/community-icons.md b/docs/contribute/concepts/community-icons.md new file mode 100644 index 0000000..fb60ff7 --- /dev/null +++ b/docs/contribute/concepts/community-icons.md @@ -0,0 +1,31 @@ +--- +title: Community icons +description: Understand how OpenMyo harvests the yotoicons.com catalog, searches it offline and falls back to it when Yoto's own icons fit poorly. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Community icons + +yotoicons.com is a free community site with many more icons than Yoto's catalog. To keep searches local +and the load on the site low, OpenMyo downloads its whole listing once and searches it offline. + +- [`CommunityCatalogHarvester`](../../../src/OpenMyo.Core/CommunityIcons/CommunityCatalogHarvester.cs) reads + page 1 to learn the total, then the other pages a few at a time, retrying failures. Pages that still fail + are skipped and the catalog is marked incomplete. +- [`CommunityCatalogProvider`](../../../src/OpenMyo.Core/CommunityIcons/CommunityCatalogProvider.cs) loads the + saved catalog while it is fresh, otherwise harvests. All callers share one in-flight load. An incomplete + catalog is used but harvested again on the next launch. +- The catalog reuses the same index as Yoto's icons, and for automatic matching multiplies the score by + *focus* (how much of the icon's own wording the title matched). A focused `fence` icon beats a song-lyric + icon that happens to contain "fence". Ties go to the most downloaded icon. +- [`CommunityIconFallback`](../../../src/OpenMyo.Core/Icons/CommunityIconFallback.cs) uses a community icon only + when it is a strong match and beats Yoto's best for that title (ties go to Yoto, since its icons need no + upload). If the site is unreachable, it returns nothing rather than failing. +- The importer downloads the chosen PNG and uploads it as the user's own icon, at most once per icon per run. + +## Related content + +- [Icon matching](icon-matching.md) +- [AI icon search](ai-icon-search.md) +- [Cross-cutting concerns](../architecture/cross-cutting-concerns.md#caching) diff --git a/docs/contribute/concepts/icon-matching.md b/docs/contribute/concepts/icon-matching.md new file mode 100644 index 0000000..0f7ee39 --- /dev/null +++ b/docs/contribute/concepts/icon-matching.md @@ -0,0 +1,103 @@ +--- +title: Icon matching +description: Understand how OpenMyo matches track titles to 16×16 icons with normalised words, trigram scoring, an inverted index and number icons. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Icon matching + +Given a track title such as *"It Began with a Rabbit's Foot"*, OpenMyo finds the best 16×16 icon among +thousands, for free, offline and deterministically. Read this when icon results look wrong or matching +changes. Claude is an optional extra (see [AI icon search](ai-icon-search.md)). + +## Turn text into words + +[`TextNormalizer.Keywords`](../../../src/OpenMyo.Core/Text/TextNormalizer.cs) is used on **both** sides (icon +titles and tags, and queries), so they compare like for like: lower-case, accents stripped, punctuation +removed, stop words dropped, and plurals singularised (`foxes` → `fox`). + +Two word lists in `src/OpenMyo.Core/Text/` tune matching. Both are embedded text files you can edit without +touching code: + +- `WeakWords.txt`: words that rarely describe a picture (verbs, filler, `little`, `bonus`). They still + count, but at a fraction of a normal word's weight. +- `Synonyms.txt`: `head: related, words`, so a title can match an icon tagged with a related word. + +## Trigram similarity + +`Trigrams` works like PostgreSQL's `pg_trgm`. A word is padded and cut into overlapping three-character +windows, and similarity is shared ÷ total distinct (Jaccard): + +```text +star → " s" " st" "sta" "tar" "ar " (5) +start → " s" " st" "sta" "tar" "art" "rt " (6) +shared 4, total distinct 7 → similarity 0.57 +``` + +This tolerates plurals, typos and word forms without a dictionary. + +## The index and the score + +[`IconIndex`](../../../src/OpenMyo.Core/Icons/IconIndex.cs) is built once from a list of icons. Each icon gets +terms: its title words at full weight and tag words slightly lower (tags are broader). An inverted index +maps each trigram to the icons that have it, so a search only scores icons sharing at least one trigram +with the query (or a synonym), not the whole catalog. + +[`IconScorer`](../../../src/OpenMyo.Core/Icons/IconScorer.cs) scores one icon against the query words: + +1. For each query word, take its **best** similarity against the icon's terms: exact word beats synonym + beats trigram similarity, scaled by the term weight. +2. A weak best counts as 0, so `star` vs `start` counts but random overlaps do not. +3. The score is the **weighted average** over query words (weak words weigh less). + +So icons that match *more* of the subject words win, and filler words barely move the score. Ties are +broken by the shorter icon title. + +## Where the indexed icons come from + +[`IconIndexProvider`](../../../src/OpenMyo.Core/Icons/IconIndexProvider.cs) builds the shared index from: + +- **Yoto's public icons** plus the user's own uploads, via `IIconCatalog`; +- **library icons**: every icon already used in the user's playlists. Many are not in the public catalog, + so the titles of the chapters they were used on become their tags. Searching `connie` then finds the icon + already used for Connie episodes. + +When both know an icon, the catalog entry wins (its tags are curated). The index is rebuilt lazily after +`Invalidate()`, which is called whenever an icon is uploaded, and after each library load. + +## From titles to assigned icons + +### Import suggestions + +[`IconSuggester`](../../../src/OpenMyo.Core/Icons/IconSuggester.cs) searches each title as-is for a handful of +candidates. A track whose best score is weak is "unsure". If the request opted into AI (the import screen +does not), only the unsure titles go to Claude, and its keywords' matches rank ahead of the title's. A track +with no matches at all falls back to matches for the playlist title. + +### Auto-match in the editor and MCP + +[`IconAutoAssigner`](../../../src/OpenMyo.Core/Icons/IconAutoAssigner.cs): + +1. Skips chapters that already have an icon, unless "replace existing" is on. +2. Finds **series words**: words in at least half of the titles. They name the show, not the episode, so + they are ignored. +3. Reduces each title to its subject: strips numbering, bracketed asides, `Part 2`, a leading `Bonus!`, + weak words and series words. `It Began with a Rabbit's Foot` → `Rabbit's Foot`. +4. Runs `IconSuggester` on those queries. +5. Asks the community fallback (see [Community icons](community-icons.md)) for any title where yotoicons.com + scores better than Yoto's best. +6. Sets the winner on each chapter and its tracks. Nothing is saved; the caller saves. + +### Number icons + +Track *n* can get an icon showing *n*. Yoto's own number icon is used when it exists; otherwise a 16×16 PNG +is drawn and uploaded with a recognisable title, so later runs find it in the user's icons instead of +uploading again. The code is in `src/OpenMyo.Core/Icons/` (`NumberIconMaker`). + +## Related content + +- [AI icon search](ai-icon-search.md) +- [Community icons](community-icons.md) +- [Improve icon matches](../how-to/improve-icon-matches.md) +- [Match icons](../../user/match-icons.md) diff --git a/docs/contribute/concepts/import-pipeline.md b/docs/contribute/concepts/import-pipeline.md new file mode 100644 index 0000000..820c53f --- /dev/null +++ b/docs/contribute/concepts/import-pipeline.md @@ -0,0 +1,83 @@ +--- +title: Import pipeline +description: Understand how OpenMyo turns dropped folders and files into playlists, from grouping and track order to title cleaning, artwork and publishing. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Import pipeline + +The user drops folders or files on the import screen. +[`DraftBuilder`](../../../src/OpenMyo.Core/Import/DraftBuilder.cs) turns them into playlist drafts with no +network access. Then the screen asks for icon suggestions, the user reviews, and +[`PlaylistPublisher`](../../../src/OpenMyo.Core/Publishing/PlaylistPublisher.cs) uploads and creates each +playlist. Podcast feeds skip `DraftBuilder` but join the same screen and publishing path. See +[Podcast feed import](podcast-feed-import.md). + +## Which files become which playlist + +- Dropped folders are expanded recursively to audio files; hidden files are skipped. +- **Every folder that directly holds audio becomes one playlist.** +- **Disc folders merge into their parent.** A folder named like `CD1`, `Disc 2` or `disk_03` belongs to the + folder above it, so a two-CD audiobook becomes one playlist. + +## Track order + +Tracks sort by disc first (disc tag, else the `CD 2` folder number, else 1). Within a disc the importer uses +the most trustworthy signal that **every** file has: + +1. Track-number tags, but only if all files have one and no two clash on the same disc. +2. Otherwise, a leading number in every file name (`01 …`, `Track 3`, `2-05 …`). +3. Otherwise, natural file-name order (so `2` sorts before `10`). + +"All or nothing" matters: mixing tagged and untagged files would interleave them. + +## Titles + +The raw title for each track is the tag title, unless it is empty or a placeholder like `Track 01`, in which +case the file name. The playlist title is the album tag if every track agrees on it, otherwise the folder +name. + +[`TitleCleaner.CleanAll`](../../../src/OpenMyo.Core/Text/TitleCleaner.cs) then cleans the whole list together. +Each rule can be switched off in `TitleCleanupOptions` (the editor's clean-up panel exposes them). The rules +cover: + +- separators (`_`, `%20`, dots when there are no spaces) and web addresses; +- noise in brackets (`(Official Audio)`, `[320 kbps]`) and anything in `[square brackets]`; +- numbering (`CD1 `, `1-03 `, `03 - `, `Track 3.`); +- a bare leading number: removed if zero-padded (`01 Song`), otherwise only when **every** title starts with + a digit, so `99 Red Balloons` survives in a normal list; +- ALL CAPS or all lower case → Title Case; +- user find/replace, and a shared `Artist - ` prefix on every title. + +If cleaning leaves nothing, the raw title is kept, and results are cut to Yoto's 140-character limit. The +bracket rule is turned off when most titles start with `[`, because then `[051] Connie` is the user's own +numbering, not junk. + +## Artwork + +Artwork sources are a file, or "the picture embedded in this audio file". Nothing is read until publishing. + +- **Cover**: an image named like `cover`, `folder` or `front`; else the only image in the folder that is not + a track sidecar; else the first embedded picture. +- **Per-track icon art**: an image with the same base name as the audio file (`03 Owl.mp3` + `03 Owl.png`). + Embedded pictures count only when tracks carry *different* pictures; identical embedded art is the album + cover, not an icon. + +## Publishing + +- Tracks upload in parallel (a setting). Results go into a fixed array by index, so parallelism never + changes the order. +- For each track, the icon is the chosen one. If none was chosen, the per-track icon art is uploaded as a + custom icon; if there is none, the track has no icon. +- Each track becomes one chapter with one track, keys `01`, `02`, … The cover is uploaded, then one + `SaveAsync` creates the card. +- "Add tracks" in the editor does the same via `PlaylistMediaService`, numbering after the existing chapters, + and runs added files through `DraftBuilder` so they are cleaned and ordered like an import. + +## Related content + +- [Podcast feed import](podcast-feed-import.md) +- [Icon matching](icon-matching.md) +- [Upload media](media-uploads.md) +- [Import folders of audio as playlists](../../user/import-folders.md) diff --git a/docs/contribute/concepts/library-and-editor.md b/docs/contribute/concepts/library-and-editor.md new file mode 100644 index 0000000..bb5ccee --- /dev/null +++ b/docs/contribute/concepts/library-and-editor.md @@ -0,0 +1,58 @@ +--- +title: Library and editor +description: Understand how the library loads and filters playlists, how the editor saves changes, and how images are cached and drawn. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Library and editor + +## Loading the library + +[`LibraryViewModel.RefreshAsync`](../../../src/OpenMyo.App/Screens/Library/LibraryViewModel.cs) shows rows as +soon as the listing returns, then loads each card's details in parallel and reports every result back to the +UI thread through `Progress`. Details come from the `updatedAt` card cache when the card is unchanged (see +[Read and save cards](read-and-save-cards.md)). + +Each row gets its issue flags from `PlaylistHealth` in Core: no tracks, any chapter without an icon, no +cover. The filter chips are just these flags: "All" clears the filter, problem chips toggle and combine, and +a row shows when it has every chosen issue. When every card is loaded, `ScreenLinks` feeds the icons already +in use into the icon index (see [Where the indexed icons come from](icon-matching.md#where-the-indexed-icons-come-from)). + +Selecting several rows enables the bulk actions (match missing icons, delete with a two-click confirm). The +library hands it `SelectedRows` and listens for its events; the bulk-actions view model never holds the +library. Library search also matches track titles. See [Track search](track-search.md). + +## Editing a playlist + +Selecting one row opens [`PlaylistEditorViewModel`](../../../src/OpenMyo.App/Screens/Editor/PlaylistEditorViewModel.cs). +It keeps the loaded playlist as `_original` and shows its chapters as editable rows. Any change (rename, +drag-reorder, icon, delete) sets `IsDirty`. + +- **Save** rebuilds a `Playlist` from `_original` plus the rows (each row keeps its original chapter key) and + calls `SaveAsync`. The Yoto client turns that into a patch of the raw card (see + [Read and save cards](read-and-save-cards.md)). +- **Revert** shows `_original` again. +- **Add tracks** and **Change cover** upload first and then save immediately. + +The editor's command groups live beside it in `Screens/Editor/`. They reach the editor only through +`IChapterEditor` (run work, read the current playlist, apply changed chapters), which keeps the editor file +small. + +The icon picker is hidden until the user clicks a track's icon (or while it asks for an API key an AI action +needs). The chapter selection knows nothing about the picker: while it is open, the editor points the +selection at the picker's target and, after each pick, advances to the next chapter without an icon (shared +with Import). + +## Images + +`RemoteImageCache` downloads each icon and cover URL once, keeping bytes on disk and decoded bitmaps in +memory. Concurrent requests for one URL share a download. `PixelImage` draws 16×16 icons scaled up without +blurring. + +## Related content + +- [Read and save cards](read-and-save-cards.md) +- [Navigation and commands](navigation-and-commands.md) +- [Track search](track-search.md) +- [Edit playlists](../../user/edit-playlists.md) diff --git a/docs/contribute/concepts/media-uploads.md b/docs/contribute/concepts/media-uploads.md new file mode 100644 index 0000000..d986235 --- /dev/null +++ b/docs/contribute/concepts/media-uploads.md @@ -0,0 +1,38 @@ +--- +title: Media uploads +description: Understand how OpenMyo uploads audio, cover images and icons to Yoto, including hashing, transcoding polls and progress. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Media uploads + +[`YotoMediaUploader`](../../../src/OpenMyo.Yoto/Media/YotoMediaUploader.cs) sends audio, cover images and icons +to Yoto. + +## Audio + +`UploadAudioAsync` works in five steps: + +1. Hash the file with SHA-256. +2. `GET media/transcode/audio/uploadUrl?sha256=…`. Yoto returns an upload id and, *only if it has never + seen these bytes*, a presigned upload URL. Re-importing the same file skips the upload entirely. +3. `PUT` the file to the presigned URL on the `yoto-upload` client, reporting bytes sent. Upload counts for + most of the progress bar; transcoding is the rest. +4. Poll `media/upload/{id}/transcoded` (404 means "not yet") with backoff until a timeout. +5. Return `yoto:#` with the format, duration, size and channels Yoto reports. + +## Cover + +`POST media/coverImage/user/me/upload` returns a public URL that goes in `metadata.cover.imageL`. + +## Icon + +`POST media/displayIcons/user/me/upload?autoConvert=true` (Yoto scales it to 16×16) returns a media id. The +uploader then tells the icon catalog to forget the user's icon list so the new icon shows up in searches. + +## Related content + +- [Yoto HTTP pipeline](yoto-http-pipeline.md) +- [Import pipeline](import-pipeline.md) +- [Card model](card-model.md) diff --git a/docs/contribute/concepts/navigation-and-commands.md b/docs/contribute/concepts/navigation-and-commands.md new file mode 100644 index 0000000..3b7621a --- /dev/null +++ b/docs/contribute/concepts/navigation-and-commands.md @@ -0,0 +1,68 @@ +--- +title: Navigation and commands +description: Understand how the navigation rail selects page view models, how view models talk to each other, and how relay commands wire buttons and menu items to view model code. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Navigation and commands + +## Navigation + +The window is a narrow navigation rail and a content area. Rail entries are `SidebarItem`s held by +[`MainViewModel`](../../../src/OpenMyo.App/Screens/Shell/MainViewModel.cs) in two lists: top items (Library, +Import) and bottom items (Settings). Selecting one calls `MainViewModel.Navigate`, which sets `CurrentPage` +to a page view model. The main window shows `CurrentPage` in a `ContentControl`, and its `DataTemplates` +choose the view for each view model type. Page view models are singletons, so a page keeps its state when +the user navigates away and back. + +Panels inside a page, such as the title clean-up panel or the icon picker, are child view models exposed as +properties of the page view model and embedded in the page view with `DataContext="{Binding …}"`. For steps, +see [Add a page to the navigation rail](../how-to/add-navigation-page.md) and +[Add a panel to an existing screen](../how-to/add-panel.md). + +## How view models talk to each other + +- **Parent → child:** a parent owns its children (constructor or property) and calls them directly. +- **Child → parent:** a child raises an event about itself (`IconChosen`, `RowsDeleted`); it never holds its + parent. Where a child needs the parent's services, it gets a small interface (`IChapterEditor`, + `IReorderableOwner`), not the parent type. +- **Page → page:** never directly. + [`ScreenLinks`](../../../src/OpenMyo.App/Composition/ScreenLinks.cs) subscribes to page events and calls + the other page, so every cross-page link is in one file. + +## Commands + +Every button and menu item runs a command on a view model: the view binds `Command="{Binding …}"`, and the +view model declares the method with `[RelayCommand]`. How the pieces fit: + +1. **The name is generated.** `[RelayCommand]` on `RematchAllIconsAsync` makes a `RematchAllIconsCommand` + property at compile time: the generator drops `Async` and adds `Command`. The class must be `partial`. + Press F12 on the name to see the generated code. +2. **Async commands block double runs.** A method that returns `Task` becomes an `IAsyncRelayCommand`, + which reports `CanExecute = false` while it runs, so the control greys out until the work finishes. +3. **`CanExecute` drives enabled state.** Save and Revert use `[RelayCommand(CanExecute = nameof(IsDirty))]`; + `[NotifyCanExecuteChangedFor]` on the backing field re-checks them when it changes. +4. **Command groups keep view models small.** The editor exposes `Icons`, `Batch` and `Cleanup` as + properties, and the view binds through them (`Icons.…`, `Batch.…`). They live in + [`Screens/Editor/Commands/`](../../../src/OpenMyo.App/Screens/Editor/Commands). + +## Commands versus Click handlers + +| | `Click` handler | Command | +|---|---|---| +| Lives in | View code-behind | View model | +| Enabled state | Set `IsEnabled` by hand | From `CanExecute`, and while an async command runs | +| Reuse | One control | Button, menu item and `KeyBinding` share one command | +| Testing | Needs a UI | Call `Execute` on the view model | + +`Click` and other events stay in code-behind only for view-only work (focus, drag-and-drop plumbing, +opening a picker), per [CODESTANDARDS](../../../CODESTANDARDS.md) §8. References: +[Avalonia commanding](https://docs.avaloniaui.net/docs/input-interaction/commanding), +[MVVM Toolkit source generators](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/generators/overview). + +## Related content + +- [App start-up and composition](app-startup.md) +- [Library and editor](library-and-editor.md) +- [Add a page to the navigation rail](../how-to/add-navigation-page.md) diff --git a/docs/contribute/concepts/podcast-feed-import.md b/docs/contribute/concepts/podcast-feed-import.md new file mode 100644 index 0000000..98f8ce9 --- /dev/null +++ b/docs/contribute/concepts/podcast-feed-import.md @@ -0,0 +1,37 @@ +--- +title: Podcast feed import +description: Understand how the From Feed dialog previews a podcast, filters episodes, downloads them in parallel and builds a draft. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Podcast feed import + +The **From Feed…** dialog previews a podcast before anything downloads, then turns the chosen episodes into +a draft for the [import pipeline](import-pipeline.md). + +## Flow + +1. [`FeedUrl`](../../../src/OpenMyo.Core/Feeds/FeedUrl.cs) accepts http(s) links, `feed://`/`itpc://` + subscribe links and bare addresses. A link pasted anywhere on the import screen opens the dialog with it. +2. `FeedParser` reads RSS 2.0 with the iTunes extensions. Only items with an audio enclosure count. Episodes + are put oldest first, by `pubDate` when every item has one, otherwise in reverse feed order. DTDs and + external entities are never resolved. +3. The user ticks episodes (a cap applies to how many can be downloaded at once) and can narrow the list + with length limits (episodes with no length in the feed pass) and words to include or exclude. + Filtered-out episodes are hidden and unticked. One order toggle sets both the list order and the track + order on the card. +4. `FeedImporter` downloads them in parallel (a setting; each row shows its own progress) into the cache + folder, with the show artwork as the cover (type sniffed from the bytes; a broken image link only loses + the cover). It builds the draft directly, not through `DraftBuilder`: the feed's order and titles are more + reliable than podcast tags. Titles still go through `TitleCleaner`, and the show title becomes the + playlist title. +5. The draft joins the import screen like any other. Its download folder is deleted when the draft is + published, discarded or cleared; anything left behind (a crash, the app closed) is swept on a later feed + download. + +## Related content + +- [Import pipeline](import-pipeline.md) +- [Cross-cutting concerns](../architecture/cross-cutting-concerns.md#caching) +- [Import a podcast feed](../../user/import-podcast-feed.md) diff --git a/docs/contribute/concepts/read-and-save-cards.md b/docs/contribute/concepts/read-and-save-cards.md new file mode 100644 index 0000000..5829b6f --- /dev/null +++ b/docs/contribute/concepts/read-and-save-cards.md @@ -0,0 +1,59 @@ +--- +title: Read and save cards +description: Understand how OpenMyo reads cards, caches them by updatedAt, and saves by patching the raw JSON so unknown fields survive. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Read and save cards + +[`YotoPlaylistRepository`](../../../src/OpenMyo.Yoto/Content/YotoPlaylistRepository.cs) implements +`IPlaylistRepository` against Yoto's `/content` API. + +| Call | Request | Then | +|---|---|---| +| `ListAsync` | `GET content/mine` | One summary per card; cards with invalid ids are dropped | +| `GetAsync(summary)` | `GET content/{id}`, unless the cache has it | Raw JSON mapped to a playlist | +| `SaveAsync` | `POST content` | Response stored in the cache, mapped back | +| `DeleteAsync` | `DELETE content/{id}` | Removed from the cache | + +## Caching by updatedAt + +The card cache keeps the last raw JSON of every card, in memory and on disk. `GetAsync` reuses it only when +its `updatedAt` equals the one in the fresh listing, so an unchanged library loads with one request. Disk +failures are ignored, since the cache is only an optimisation. See +[Cross-cutting concerns](../architecture/cross-cutting-concerns.md#caching). + +## Saving without losing data + +Because saving replaces the whole card, rebuilding JSON from the domain model would delete every field +OpenMyo does not model (and Yoto adds fields over time). So a save *patches* the last-fetched document +instead. [`CardComposer`](../../../src/OpenMyo.Yoto/Content/CardComposer.cs) is the entry point: + +1. `SaveAsync` takes the cached raw card (or fetches it) as the base. +2. The composer deep-clones it, removes server-managed fields (`createdAt`, `updatedAt`, `_id`, `userId`), + checks title lengths, and sets the title, cover URL and totals. +3. It rebuilds `content.chapters` in the domain order: + - Each domain chapter **clones the raw chapter with the same `key`**, so unknown fields carry over. + Each raw item is used at most once. New chapters start empty. + - Keys are then **renumbered** (`01`, `02`, …) and the chapter `overlayLabel` set to the position. This is + how reordering works: the domain keeps the old key so the right raw node is found, and the save writes + the new position. + - Tracks follow the same rules, except that a track's `overlayLabel` counts tracks across the whole card + while its key restarts at `01` in each chapter. Media fields (`format`, `duration`, `fileSize`, + `channels`) are only written when the track is new or its `trackUrl` changed, so Yoto's own values are + kept otherwise. + - Icons are written as `display.icon16x16 = "yoto:#"` only for a valid media id; otherwise the field + is removed. + +## Reading + +Reading is the mirror: the mapper never mutates the document. A chapter without its own icon inherits the +first track icon it finds. + +## Related content + +- [Card model](card-model.md) +- [Library and editor](library-and-editor.md) +- [Add a card field](../how-to/add-card-field.md) +- [Design invariants](../architecture/invariants.md) diff --git a/docs/contribute/concepts/sign-in-and-tokens.md b/docs/contribute/concepts/sign-in-and-tokens.md new file mode 100644 index 0000000..720e6c2 --- /dev/null +++ b/docs/contribute/concepts/sign-in-and-tokens.md @@ -0,0 +1,64 @@ +--- +title: Sign-in and tokens +description: Understand OpenMyo's OAuth sign-in with PKCE, token storage, and the locks that keep single-use refresh tokens safe. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Sign-in and tokens + +## Sign-in flow + +Each user registers their own public OAuth client at yoto.dev and pastes its id into Settings. There is no +client secret. Sign-in is Authorization Code + PKCE with a loopback redirect: + +```mermaid +sequenceDiagram + participant A as App + participant L as Loopback listener + participant B as System browser + participant Y as Yoto login + participant S as Secret store + + A->>A: PKCE verifier, challenge, state + A->>L: Start listening on /callback + L->>B: Open authorize URL + B->>Y: User signs in and approves + Y->>B: Redirect to /callback?code&state + B->>L: GET /callback + L-->>A: code (state checked) + A->>Y: code + verifier + Y-->>A: access token, refresh token + A->>S: Store refresh token and granted scope +``` + +The listener ignores requests whose `state` does not match and gives up after a timeout. The loopback +redirect URI is fixed, because the user must register it with their OAuth client. + +## Token ownership + +[`YotoSession`](../../../src/OpenMyo.Yoto/Auth/YotoSession.cs) owns the tokens afterwards: + +- The **access token** lives only in memory. It is refreshed shortly before expiry, or when a request gets + a 401. +- The **refresh token** lives in the secret store. **Yoto refresh tokens are single-use:** each refresh + returns a new one, and the old one stops working. Two refreshes with the same token sign the user out. + So every refresh is serialised twice: + - within the process by a `SemaphoreSlim`; + - across processes (the app and the Claude Desktop connector can run at once) by + [`RefreshLock`](../../../src/OpenMyo.Yoto/Auth/RefreshLock.cs), an exclusively opened file in the data + folder. The OS releases it if a process dies. + + The refresh token is read *inside* both locks, because the other process may have just replaced it. +- `RefreshAccessTokenAsync(rejectedToken)` only refreshes if the current token is still the rejected one. + So ten requests that all get a 401 cause one refresh, not ten. +- A 400/401/403 from the token endpoint clears the session (the user must sign in again). +- `TryRestoreAsync` also compares the stored scope with the current scope list. If the app now asks for + more scopes, the old token is dropped, because refreshing cannot widen a grant. + +## Related content + +- [Yoto HTTP pipeline](yoto-http-pipeline.md) +- [App start-up and composition](app-startup.md) +- [Claude Desktop connector](claude-desktop-connector.md) +- [Cross-cutting concerns](../architecture/cross-cutting-concerns.md) diff --git a/docs/contribute/concepts/track-search.md b/docs/contribute/concepts/track-search.md new file mode 100644 index 0000000..21d6b1d --- /dev/null +++ b/docs/contribute/concepts/track-search.md @@ -0,0 +1,28 @@ +--- +title: Track search +description: Understand how the library search matches playlist and track titles together without extra network requests. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Track search + +The library already loads every playlist's chapters in the background (from the `updatedAt` card cache), so +search makes no extra requests. See [Library and editor](library-and-editor.md#loading-the-library). + +- [`TrackSearch.Match`](../../../src/OpenMyo.Core/Library/TrackSearch.cs) checks the playlist title and each + chapter title. A title matches when it contains every word, ignoring case and accents, and the matched + ranges are returned for highlighting. A chapter is a track to the user, so its 1-based position is the + track number shown. +- Playlists whose title matches come first, then those that match only on tracks. Clicking a matching track + opens the playlist with that track selected and scrolled into view. +- Searching while details are still loading inserts newly matching rows in place, rather than rebuilding the + list, so the playlist open in the editor keeps its unsaved edits. The summary line says how many playlists + are still being checked, so an incomplete result isn't mistaken for "no results". +- The MCP tool `search_tracks` uses the same matching. See [Claude Desktop connector](claude-desktop-connector.md). + +## Related content + +- [Library and editor](library-and-editor.md) +- [Claude Desktop connector](claude-desktop-connector.md) +- [Search and filter the library](../../user/library-and-search.md) diff --git a/docs/contribute/concepts/yoto-http-pipeline.md b/docs/contribute/concepts/yoto-http-pipeline.md new file mode 100644 index 0000000..40480e5 --- /dev/null +++ b/docs/contribute/concepts/yoto-http-pipeline.md @@ -0,0 +1,34 @@ +--- +title: Yoto HTTP pipeline +description: Understand the named HTTP clients, retry and auth handlers that every OpenMyo call to Yoto goes through. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Yoto HTTP pipeline + +[`AddYoto`](../../../src/OpenMyo.Yoto/ServiceCollectionExtensions.cs) registers three named clients: + +| Client | Handlers | Used for | +|---|---|---| +| `yoto-api` | retry, then auth | Every API call | +| `yoto-auth` | none | Token exchange and refresh | +| `yoto-upload` | none, no timeout | `PUT` of audio bytes to presigned storage URLs | + +## Handlers + +A request on `yoto-api` goes through the handlers in order: + +1. The retry handler retries **429 and 503** a few times, honouring `Retry-After`. +2. The auth handler adds `Authorization: Bearer …`. On a **401** it asks the session for a new token once and + resends once. + +Both only resend when the body can be sent again. The upload client deliberately has no auth handler, so the +bearer token never reaches the storage host. Non-success responses become `YotoApiException`. + +## Related content + +- [Sign-in and tokens](sign-in-and-tokens.md) +- [Read and save cards](read-and-save-cards.md) +- [Upload media](media-uploads.md) +- [Add a Yoto endpoint call](../how-to/call-yoto-endpoint.md) diff --git a/docs/contribute/concepts/yoto-player-control.md b/docs/contribute/concepts/yoto-player-control.md new file mode 100644 index 0000000..6540110 --- /dev/null +++ b/docs/contribute/concepts/yoto-player-control.md @@ -0,0 +1,74 @@ +--- +title: Yoto player control +description: Understand how OpenMyo plays audio on a Yoto player over MQTT, including the output picker, protocol, connection lifecycle and safety defaults. +ms.topic: concept-article +ms.date: 11/16/2026 +--- + +# Yoto player control + +## Playing on a Yoto player + +The output button in the now-playing bar lists **This computer** and every player on the account. It works +like choosing a speaker on a phone: + +- **Changing the output never changes what a player is doing.** If the app itself is playing, that moves + to the chosen player at the same track and position, but only when the player is idle. A player that is + already playing or paused carries on, and the bar shows it with a notice. +- **Players already playing show in the bar** from sign-in. **Control** makes that player the output without + touching what it plays. +- Seeking happens only when the slider is let go. The slider also moves by itself when a new track length + arrives, and seeking is a `card/start`, so treating that as a seek restarted the track in a loop. +- While a player is chosen, the bar stays visible and names the player, so it is always clear where audio goes. +- **The choice is not saved.** Every launch starts on this computer, so opening the app never plays out loud + in another room unexpectedly. +- Files being imported exist only on this computer, so they always play locally. +- If the player stops answering, the app tries once more, then falls back to this computer with a notice. + +## Protocol + +| What | How | +|---|---| +| List players | `GET /device-v2/devices/mine` (`family:devices:view`) | +| Commands | MQTT publish to `device/{id}/command/card/start`, `card/pause`, `card/resume`, `card/stop`, `volume/set` | +| State | Subscribe to `device/{id}/data/events`. A message may carry only the fields that changed, so each one is merged into the previous state. | +| Broker | Yoto's AWS IoT endpoint, MQTT 3.1.1 over WebSockets | +| Auth | Username `?x-amz-customauthorizer-name=PublicJWTAuthorizer`, password = the access token (`family:devices:control`), client id `DASH` | + +Players report volume in steps and their parental limit as `volumeMax`; the bar's slider works in steps and +stops at that limit. `volume/set` takes a percentage instead, so the app converts, rounding up so the player +lands on the step asked for. + +[`YotoPlayerRemote`](../../../src/OpenMyo.Yoto/Devices/YotoPlayerRemote.cs) turns off MQTTnet's packet +fragmentation. AWS IoT closes the connection when an MQTT packet arrives split across WebSocket frames. +Subscribing still works with fragmentation on, so the fault only shows when the first command is sent. + +`card/start` addresses the card by its short link, `https://yoto.io/`, plus `chapterKey`, `trackKey` +and `secondsIn`. Yoto has no "next" command, so next, previous and seeking are `card/start` again with the +neighbouring chapter or a new `secondsIn`. + +## Connection lifecycle + +`YotoPlayerRemote` holds one shared connection per player; the bar, the live list and commands all use it: + +- From sign-in the app connects to every online player so it can show ones already playing. Watching only + listens. Signing out closes every connection. +- Switching the output away from a player does not disconnect it; the live list keeps watching it. +- Yoto closes connections that are quiet for about five minutes, so the remote publishes `events/request` + just under that. That also asks the player for fresh state. +- The broker checks the token only when connecting. A dropped connection is reopened with a fresh token on + the next command. After an unexpected drop the connection waits briefly and tries once more, then reports + the player as gone (the bar falls back to this computer; the live list drops its line). +- The client id is fixed per player, so only one connection per player can be open at a time. The Claude + Desktop tools run in a separate process and disconnect right after each command. That keeps any clash + with the app brief, and the app's reconnect recovers from it. + +Players report changes rather than a steady clock, so the bar ticks the position forward locally between +reports. + +## Related content + +- [Track search](track-search.md) +- [Sign-in and tokens](sign-in-and-tokens.md) +- [Claude Desktop connector](claude-desktop-connector.md) +- [Play audio](../../user/play-audio.md) diff --git a/docs/contribute/how-to/add-card-field.md b/docs/contribute/how-to/add-card-field.md new file mode 100644 index 0000000..c6dd897 --- /dev/null +++ b/docs/contribute/how-to/add-card-field.md @@ -0,0 +1,33 @@ +--- +title: Add a field to a card or chapter +description: Store a new field on a Yoto card or chapter by extending the domain record, the mapper and the composers without losing unknown fields. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Add a field to a card or chapter + +In this article, you add a new property to a card or chapter so OpenMyo reads it from Yoto and writes it back on save, without dropping fields it doesn't model. + +## Steps + +1. Add the property to the record in [`Core/Playlists`](../../../src/OpenMyo.Core/Playlists). + +1. Read it in [`CardMapper`](../../../src/OpenMyo.Yoto/Content/CardMapper.cs). + +1. Write it in [`CardComposer`](../../../src/OpenMyo.Yoto/Content/CardComposer.cs) or + [`ChapterComposer`](../../../src/OpenMyo.Yoto/Content/ChapterComposer.cs) by setting that one field on the + cloned node. + + > [!IMPORTANT] + > Never build the node from scratch. A save replaces the whole card, so a rebuilt node deletes fields OpenMyo doesn't model. See [Read and save cards](../concepts/read-and-save-cards.md). + +1. Add a round-trip case to [`CardComposerTests`](../../../tests/OpenMyo.Yoto.Tests/Content/CardComposerTests.cs) + with the sample JSON in [`Samples`](../../../tests/OpenMyo.Yoto.Tests/Content/Samples.cs), and assert that an + unrelated field is still present after the save. + +## Related content + +- [Card model](../concepts/card-model.md) +- [Read and save cards](../concepts/read-and-save-cards.md) +- [Invariants](../architecture/invariants.md) diff --git a/docs/contribute/how-to/add-claude-desktop-tool.md b/docs/contribute/how-to/add-claude-desktop-tool.md new file mode 100644 index 0000000..a4784b5 --- /dev/null +++ b/docs/contribute/how-to/add-claude-desktop-tool.md @@ -0,0 +1,33 @@ +--- +title: Add a Claude Desktop tool +description: Add a new MCP tool that Claude Desktop can call, including its attributes, guard, validation, registration, instructions and tests. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Add a Claude Desktop tool + +In this article, you add an MCP tool to the connector so Claude Desktop can call it. + +## Steps + +1. Add a public method with `[McpServerTool(Name = "verb_noun", …)]` and a `[Description]` on the method + and each parameter, in a `[McpServerToolType]` class in the matching feature folder of [`OpenMyo.Mcp`](../../../src/OpenMyo.Mcp). Set `ReadOnly`, `Destructive` and `Idempotent` to match + what it does. + +1. Wrap the body in [`ToolGuard.RunAsync`](../../../src/OpenMyo.Mcp/Support/ToolGuard.cs). Throw `McpException` with a plain sentence for bad input. + +1. Load playlists through the lookup helpers in `Support/`, validate all + input before saving anything, save once, and return the previous values so Claude can undo. + +1. Register a new tool class in [`AddMcpTools`](../../../src/OpenMyo.Mcp/ServiceCollectionExtensions.cs); its methods are found by attribute. + +1. Describe when to use it in the `Instructions` text in [`McpEntry`](../../../src/OpenMyo.Mcp/McpEntry.cs). + +1. Test it with [`McpWorld`](../../../tests/OpenMyo.Mcp.Tests/McpWorld.cs) in + [`tests/OpenMyo.Mcp.Tests`](../../../tests/OpenMyo.Mcp.Tests). + +## Related content + +- [Claude Desktop connector](../concepts/claude-desktop-connector.md) +- [Architecture overview](../architecture/overview.md#projects) diff --git a/docs/contribute/how-to/add-domain-logic.md b/docs/contribute/how-to/add-domain-logic.md new file mode 100644 index 0000000..d148b60 --- /dev/null +++ b/docs/contribute/how-to/add-domain-logic.md @@ -0,0 +1,36 @@ +--- +title: Add domain logic +description: Add a new title clean-up rule, library filter, matcher or similar pure logic to OpenMyo.Core, register it, test it and call it from the UI or a tool. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Add domain logic + +In this article, you add pure logic to `OpenMyo.Core`, such as a new title clean-up rule, library filter or matcher, and wire it up so the app or a Claude Desktop tool can call it. + +## Steps + +1. Put the logic in the feature folder under [`OpenMyo.Core`](../../../src/OpenMyo.Core) as a pure class or + static method. Take dependencies through Core interfaces only. + +1. Register it in [`AddCore`](../../../src/OpenMyo.Core/ServiceCollectionExtensions.cs) if it has state or + dependencies. + +1. Test it in the matching folder of [`tests/OpenMyo.Core.Tests`](../../../tests/OpenMyo.Core.Tests), using the + fakes in [`Fakes`](../../../tests/OpenMyo.Core.Tests/Fakes). + +1. Call it from a view model ([Add a page to the navigation rail](add-navigation-page.md), [Add a panel to an existing screen](add-panel.md)) or an MCP tool + ([Add a Claude Desktop tool](add-claude-desktop-tool.md)). + +## Examples + +- **Title clean-up rule:** a property on [`TitleCleanupOptions`](../../../src/OpenMyo.Core/Text/TitleCleanupOptions.cs) and a step in [`TitleCleaner.Clean`](../../../src/OpenMyo.Core/Text/TitleCleaner.cs). +- **Library filter:** a flag in [`PlaylistIssues`](../../../src/OpenMyo.Core/Library/PlaylistIssues.cs), a check in [`PlaylistHealth`](../../../src/OpenMyo.Core/Library/PlaylistHealth.cs), and a chip in + `LibraryViewModel.Chips` ([`LibraryViewModel`](../../../src/OpenMyo.App/Screens/Library/LibraryViewModel.cs)); matching and counts come from the flag. + +## Related content + +- [Architecture overview](../architecture/overview.md#projects) +- [Invariants](../architecture/invariants.md) +- [Improve icon matches](improve-icon-matches.md) diff --git a/docs/contribute/how-to/add-navigation-page.md b/docs/contribute/how-to/add-navigation-page.md new file mode 100644 index 0000000..5d31865 --- /dev/null +++ b/docs/contribute/how-to/add-navigation-page.md @@ -0,0 +1,54 @@ +--- +title: Add a page to the navigation rail +description: Add a full-screen page, such as Import or Settings, to the OpenMyo navigation rail with a view model, view, registration, template and shell hook-up. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Add a page to the navigation rail + +A page is a full screen chosen from the navigation rail, like Import or Settings. In this article, you add a page called +`Reports`; replace the name with yours. + +## Steps + +1. **Create the view model** in `src/OpenMyo.App/Screens/Reports/`. Derive from + [`OperationViewModel`](../../../src/OpenMyo.App/Screens/OperationViewModel.cs) if the page runs long work, and take + services through the constructor. [`SettingsViewModel`](../../../src/OpenMyo.App/Screens/Settings/SettingsViewModel.cs) is the pattern to copy. + +1. **Create the view** beside it: a `UserControl` with `x:DataType` set, a `largeTitle` heading, and the error + banner bound to `Error`. Copy the shape of [`SettingsView`](../../../src/OpenMyo.App/Screens/Settings/SettingsView.axaml). + +1. **Register the view model** as a singleton in + [`ServiceRegistration`](../../../src/OpenMyo.App/Composition/ServiceRegistration.cs). The container validates + on build, so a missing registration fails at start-up. + +1. **Map the view model to the view** with a `DataTemplate` in + [`MainWindow.axaml`](../../../src/OpenMyo.App/Screens/Shell/MainWindow.axaml), next to the existing ones: + + ```xml + + ``` + +1. **Add a rail icon**: a `StreamGeometry` in [`Styles/Theme.axaml`](../../../src/OpenMyo.App/Styles/Theme.axaml) + next to the existing icons. + +1. **Add the destination** to `SidebarDestination` in + [`SidebarItem.cs`](../../../src/OpenMyo.App/Screens/Shell/SidebarItem.cs). + +1. **Hook it into the shell** in [`MainViewModel`](../../../src/OpenMyo.App/Screens/Shell/MainViewModel.cs): take the + view model in the constructor, expose it, add a sidebar item, and add a case to `Navigate`. If the shell's + constructor is getting large, follow [CODESTANDARDS.md](../../../CODESTANDARDS.md) §2. + + If the new page must react to another page (for example refresh after an import), add that link to + [`ScreenLinks`](../../../src/OpenMyo.App/Composition/ScreenLinks.cs), not to either page. + +## Verify + +Run `dotnet build OpenMyo.sln`, run the app, click the new rail icon, and check the page +with the keyboard alone. + +## Related content + +- [Navigation and commands](../concepts/navigation-and-commands.md) +- [Add a panel to an existing screen](add-panel.md) diff --git a/docs/contribute/how-to/add-panel.md b/docs/contribute/how-to/add-panel.md new file mode 100644 index 0000000..f120095 --- /dev/null +++ b/docs/contribute/how-to/add-panel.md @@ -0,0 +1,43 @@ +--- +title: Add a panel to an existing screen +description: Add a panel, such as the title clean-up panel or the icon picker, to an existing OpenMyo screen with a child view model and an embedded view. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Add a panel to an existing screen + +A panel is part of a screen, like the title clean-up panel in the editor or the icon picker beside the +import list. In this article, you add a panel called `ChapterNotes` to the editor. + +## Steps + +1. **Create the view model** in the screen's folder, for example + `Screens/Editor/ChapterNotesViewModel.cs`. Derive from `ObservableObject`, like + [`TitleCleanupViewModel`](../../../src/OpenMyo.App/Screens/Editor/TitleCleanupViewModel.cs) and [`IconPickerViewModel`](../../../src/OpenMyo.App/Screens/IconPicker/IconPickerViewModel.cs). + +1. **Expose it from the parent view model** as a read-only property: + - if it only needs the parent's state, create it in the parent's constructor, as + [`PlaylistEditorViewModel`](../../../src/OpenMyo.App/Screens/Editor/PlaylistEditorViewModel.cs) does with `Cleanup = new TitleCleanupViewModel(Chapters, Selection)`; + - if it needs services, register it in [`ServiceRegistration`](../../../src/OpenMyo.App/Composition/ServiceRegistration.cs) (transient when each screen needs + its own instance, as with `IconPickerViewModel`) and take it in the parent's constructor. + +1. **Create the view.** Create `Screens/Editor/ChapterNotesView.axaml` as a `UserControl` with + `x:DataType="vm:ChapterNotesViewModel"`. + +1. **Embed it** in the parent view, binding its `DataContext` to the property, as + [`PlaylistEditorView.axaml`](../../../src/OpenMyo.App/Screens/Editor/PlaylistEditorView.axaml) does: + + ```xml + + ``` + +## Verify + +Build, run, and open the panel from the screen with the mouse and the keyboard. + +## Related content + +- [Navigation and commands](../concepts/navigation-and-commands.md) +- [Add a page to the navigation rail](add-navigation-page.md) +- [Library and editor](../concepts/library-and-editor.md) diff --git a/docs/contribute/how-to/add-setting-or-secret.md b/docs/contribute/how-to/add-setting-or-secret.md new file mode 100644 index 0000000..5efb06c --- /dev/null +++ b/docs/contribute/how-to/add-setting-or-secret.md @@ -0,0 +1,35 @@ +--- +title: Add a setting or a secret +description: Add a new non-secret setting to AppSettings and the Settings screen, or a new secret to the OS secret store, without leaking it into settings or logs. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Add a setting or a secret + +In this article, you add either a setting (anything that isn't secret) or a secret (tokens and keys). + +> [!IMPORTANT] +> Never put a secret in `AppSettings`, a log or a URL. + +## Add a setting + +1. Add an `init` property with a default to [`AppSettings`](../../../src/OpenMyo.Core/Abstractions/ISettingsStore.cs). + Existing `settings.json` files get the default. + +1. Read it with [`ISettingsStore.LoadAsync`](../../../src/OpenMyo.Core/Abstractions/ISettingsStore.cs); save with `SaveAsync(current with { … })`. + +1. Show it in [`SettingsViewModel`](../../../src/OpenMyo.App/Screens/Settings/SettingsViewModel.cs) and + [`SettingsView`](../../../src/OpenMyo.App/Screens/Settings/SettingsView.axaml). + +## Add a secret + +1. Add a name to [`SecretNames`](../../../src/OpenMyo.Core/Abstractions/SecretNames.cs). + +1. Read and write it through [`ISecretStore`](../../../src/OpenMyo.Core/Abstractions/ISecretStore.cs). + +## Related content + +- [Invariants](../architecture/invariants.md) +- [Data locations (user reference)](../../user/reference/data-locations.md) +- [Navigation and commands](../concepts/navigation-and-commands.md) diff --git a/docs/contribute/how-to/call-yoto-endpoint.md b/docs/contribute/how-to/call-yoto-endpoint.md new file mode 100644 index 0000000..9329e22 --- /dev/null +++ b/docs/contribute/how-to/call-yoto-endpoint.md @@ -0,0 +1,38 @@ +--- +title: Call a new Yoto endpoint +description: Add DTOs, make an authenticated and retried call to a new Yoto API endpoint, validate ids, register the service and test it with stubbed HTTP. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Call a new Yoto endpoint + +In this article, you add a call to a Yoto API endpoint that gets retries and authentication for free. Every change also follows [CODESTANDARDS.md](../../../CODESTANDARDS.md) and passes the checks in [CONTRIBUTING.md](../../../CONTRIBUTING.md#running-checks). + +## Steps + +1. Add request and response DTOs in [`Yoto/Json`](../../../src/OpenMyo.Yoto/Json) and register each type with a + `[JsonSerializable]` line on [`YotoJsonContext`](../../../src/OpenMyo.Yoto/Json/YotoJsonContext.cs). + Serialisation is source-generated, so an unregistered type fails at runtime. + +1. Make the call in the class that owns the area (cards, media or icons; see [`YotoPlaylistRepository`](../../../src/OpenMyo.Yoto/Content/YotoPlaylistRepository.cs) for the pattern). Create the client with + `httpClientFactory.CreateClient(YotoHttpClients.Api)` to get retries and auth, and read the response + with [`YotoResponse`](../../../src/OpenMyo.Yoto/Http/YotoResponse.cs). + +1. Check any id from outside with [`CardIds`](../../../src/OpenMyo.Yoto/Content/CardIds.cs) before it goes into a URL, and escape query values. + +1. If Core needs the feature, add a method to the Core interface (or a new interface in + [`Core/Abstractions`](../../../src/OpenMyo.Core/Abstractions)) and register the implementation in + [`AddYoto`](../../../src/OpenMyo.Yoto/ServiceCollectionExtensions.cs). + +1. Test it with [`StubHttpHandler`](../../../tests/OpenMyo.Yoto.Tests/Support/StubHttpHandler.cs) in + [`tests/OpenMyo.Yoto.Tests`](../../../tests/OpenMyo.Yoto.Tests). + +1. If it needs a new OAuth scope, add it to [`YotoAuthEndpoints.Scope`](../../../src/OpenMyo.Yoto/Auth/YotoAuthEndpoints.cs). Existing users are asked to sign in + again on next launch (see [Sign-in and tokens](../concepts/sign-in-and-tokens.md)). + +## Related content + +- [Yoto HTTP pipeline](../concepts/yoto-http-pipeline.md) +- [Sign-in and tokens](../concepts/sign-in-and-tokens.md) +- [Add a field to a card or chapter](add-card-field.md) diff --git a/docs/contribute/how-to/improve-icon-matches.md b/docs/contribute/how-to/improve-icon-matches.md new file mode 100644 index 0000000..5673194 --- /dev/null +++ b/docs/contribute/how-to/improve-icon-matches.md @@ -0,0 +1,30 @@ +--- +title: Improve icon matches +description: Fix a poor automatic icon match by adding a failing test, then adjusting synonyms, weak words, query cleaning or scoring thresholds in order. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Improve icon matches + +In this article, you fix a track title that gets a poor icon, using the smallest change that works. + +## Steps + +1. Add the failing title as a test case in + [`IconAutoAssignerTests`](../../../tests/OpenMyo.Core.Tests/Icons/IconAutoAssignerTests.cs) or + [`IconQueryTests`](../../../tests/OpenMyo.Core.Tests/Text/IconQueryTests.cs). + +1. Make the smallest change that fixes it, in this order of preference: + + 1. A related word is missing: add a line to [`Synonyms.txt`](../../../src/OpenMyo.Core/Text/Synonyms.txt). + 1. A filler word is winning: add it to [`WeakWords.txt`](../../../src/OpenMyo.Core/Text/WeakWords.txt), + sorted, lower case, singular. + 1. Title noise reaches the query: extend [`IconQuery`](../../../src/OpenMyo.Core/Text/IconQuery.cs). + 1. Otherwise, change the weights or thresholds in [`IconScorer`](../../../src/OpenMyo.Core/Icons/IconScorer.cs) or [`IconSuggester`](../../../src/OpenMyo.Core/Icons/IconSuggester.cs). + +## Related content + +- [Icon matching](../concepts/icon-matching.md) +- [Community icons](../concepts/community-icons.md) +- [Add domain logic](add-domain-logic.md) diff --git a/docs/contribute/how-to/render-screen-snapshots.md b/docs/contribute/how-to/render-screen-snapshots.md new file mode 100644 index 0000000..2842f04 --- /dev/null +++ b/docs/contribute/how-to/render-screen-snapshots.md @@ -0,0 +1,26 @@ +--- +title: Render a screen without signing in +description: Render OpenMyo screens headlessly to PNG with sample data so you can check UI changes without a Yoto account. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Render a screen without signing in + +In this article, you render a screen to a PNG with sample data, so you can check a UI change without a Yoto account. + +## Steps + +1. Add a block in [`tools/OpenMyo.Snapshots`](../../../tools/OpenMyo.Snapshots) that opens your screen's view model. + +1. Run the tool: + + ```bash + dotnet run --project tools/OpenMyo.Snapshots -- [card json] + ``` + +## Related content + +- [Architecture overview](../architecture/overview.md#projects) +- [Add a panel to an existing screen](add-panel.md) +- [Add a page to the navigation rail](add-navigation-page.md) diff --git a/docs/design/decisions.md b/docs/contribute/reference/design-decisions.md similarity index 63% rename from docs/design/decisions.md rename to docs/contribute/reference/design-decisions.md index be52aa9..626e3ae 100644 --- a/docs/design/decisions.md +++ b/docs/contribute/reference/design-decisions.md @@ -1,21 +1,32 @@ --- -description: Record of the main design decisions, their reasons and what they give users; read before reversing or revisiting one. +title: Design decisions +description: Review the main design decisions in OpenMyo, why each was made, and what it gives users, before you reverse or revisit one. +ms.topic: reference +ms.date: 11/16/2026 --- # Design decisions +Read this table before you reverse or revisit a decision. + | Decision | Why | What the user gets | |---|---|---| | Avalonia, not MAUI | MAUI has no real macOS desktop target (it goes through Mac Catalyst). Avalonia runs one codebase as a normal desktop app on macOS and Windows. | The same app, with the same features, on a Mac or a Windows PC. | | PKCE, not device code | Yoto has deprecated the device code flow. Authorization Code + PKCE with a loopback redirect is the supported option for desktop apps. | Signs in on Yoto's own page in their browser; OpenMyo never sees their password. | | Each user registers their own Yoto client | No client secret can be shipped safely in an open-source binary, and there is no OpenMyo server. | Their data goes straight between their computer and Yoto, through nobody else. | -| Patch card JSON, don't rebuild it | Saving replaces the whole card, so a rebuild from domain records would delete fields OpenMyo doesn't model (see [Reading and saving cards](yoto-client.md#reading-and-saving-cards)). | Editing a card in OpenMyo never breaks settings made in the Yoto app. | -| Cache cards by `updatedAt` | Unchanged cards need no request (see [Reading and saving cards](yoto-client.md#reading-and-saving-cards)). | A large library opens in seconds after the first time. | +| Patch card JSON, don't rebuild it | Saving replaces the whole card, so a rebuild from domain records would delete fields OpenMyo doesn't model (see [Read and save cards](../concepts/read-and-save-cards.md)). | Editing a card in OpenMyo never breaks settings made in the Yoto app. | +| Cache cards by `updatedAt` | Unchanged cards need no request (see [Read and save cards](../concepts/read-and-save-cards.md)). | A large library opens in seconds after the first time. | | Claude returns keywords, not icon ids | The icon catalog never goes in the prompt. Keywords are matched locally, so everything works without Claude. | AI is optional; without an API key icon matching still works. | -| Keep Claude calls small | Claude only runs on a click, answers are cached per title, the vocabulary is capped at 1,500 words and prompt-cached, effort is `low`, and `max_tokens` scales with the request. | Using their own API key costs very little, and nothing unless they click. | +| Keep Claude calls small | Claude only runs on a click, answers are cached per title, the vocabulary is capped and prompt-cached, effort is low, and the token limit scales with the request. | Using their own API key costs very little, and nothing unless they click. | | Trigram matching by default | Fast, free, deterministic and easy to test. | Icons for a whole playlist are suggested instantly, and the same titles always get the same icons. | -| Harvest yotoicons.com instead of querying it | Searches stay instant and offline, and a free hobby site gets a few requests a week instead of one per keystroke. | Thousands more icons to choose from, with no waiting while typing. | +| Harvest yotoicons.com instead of querying it | Searches stay instant and offline, and a free hobby site gets very few requests instead of one per keystroke. | Many more icons to choose from, with no waiting while typing. | | Strict layering | Core has no UI, HTTP or platform code, so matching, ordering and cleanup stay pure and unit-tested. | Fewer regressions: the rules that shape their playlists are covered by tests. | -| MQTT for Yoto player control | Yoto accepts play, pause and volume commands only over its MQTT broker (see [players](players.md#protocol)). MQTTnet is the one extra dependency. | Any track can be sent to a Yoto player in the house, with live controls. | +| MQTT for Yoto player control | Yoto accepts play, pause and volume commands only over its MQTT broker (see [Yoto player control](../concepts/yoto-player-control.md#protocol)). MQTTnet is the one extra dependency. | Any track can be sent to a Yoto player in the house, with live controls. | | Output resets to this computer on every launch | A remembered player would make the first ▶ after opening the app play out loud in another room. | Opening OpenMyo never wakes a sleeping child. | | One search field for playlists and tracks | One place to look, as the search field already filters the library; track details are already loaded for the health filters. | Type a song name and see which playlists have it, with the matching words highlighted. | + +## Related content + +- [Architecture overview](../architecture/overview.md) +- [Invariants](../architecture/invariants.md) +- [Track search](../concepts/track-search.md) diff --git a/docs/contribute/reference/glossary.md b/docs/contribute/reference/glossary.md new file mode 100644 index 0000000..09b703c --- /dev/null +++ b/docs/contribute/reference/glossary.md @@ -0,0 +1,25 @@ +--- +title: Glossary +description: Definitions of the terms used across the OpenMyo code and documentation, such as card, chapter, media id, MCP, PKCE and trigram. +ms.topic: reference +ms.date: 11/16/2026 +--- + +# Glossary + +| Term | Meaning | +|---|---| +| Card | A Yoto playlist, stored by Yoto as one JSON document | +| Chapter | One entry in a card; what the user sees as a track. Usually holds one track | +| MYO | Make Your Own: Yoto's user-created cards | +| Media id | 43-character id of an uploaded image or icon, written as `yoto:#` | +| MCP | Model Context Protocol, how Claude Desktop calls OpenMyo's tools | +| PKCE | Proof Key for Code Exchange, the OAuth flow for apps without a client secret | +| DPAPI | Windows Data Protection API, used to encrypt secrets on Windows | +| Trigram | A three-character slice of a word, used for fuzzy matching | + +## Related content + +- [Architecture overview](../architecture/overview.md) +- [Card model](../concepts/card-model.md) +- [Icon matching](../concepts/icon-matching.md) diff --git a/docs/design/app.md b/docs/design/app.md deleted file mode 100644 index 362a8ec..0000000 --- a/docs/design/app.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -description: "Explanation of the desktop app and the Claude Desktop connector: start-up, navigation, commands, library, editor, MCP tools and other platforms; read when changing screens or connector behaviour, or porting to web or mobile." ---- - -# The desktop app and the Claude Desktop connector - -`OpenMyo.App` hosts both: the Avalonia window, and the windowless MCP connector that Claude Desktop starts. -Both build the same services, so a feature in Core is available to the screens and the tools alike. - -## Start-up and composition - -[`Program.Main`](../../src/OpenMyo.App/Program.cs) picks one of two modes: - -- **Window mode** (normal): starts Avalonia. [`App`](../../src/OpenMyo.App/App.axaml.cs) builds the service - provider and shows [`MainWindow`](../../src/OpenMyo.App/Screens/Shell/MainWindow.axaml) bound to - [`MainViewModel`](../../src/OpenMyo.App/Screens/Shell/MainViewModel.cs). -- **Connector mode** (`--mcp`): [`McpMode`](../../src/OpenMyo.App/Composition/McpMode.cs) builds the *same* - services, silently restores the Yoto session, and serves MCP over stdio. Avalonia never starts, and - nothing else may write to stdout. See [Claude Desktop connector](#claude-desktop-connector). - - -```mermaid -flowchart TD - main["Program.Main"] -->|no arguments| app["App: ServiceRegistration.Build"] - main -->|--mcp| mcp["McpMode: ServiceRegistration.Build"] - app --> win["MainWindow + MainViewModel.InitializeAsync"] - win --> restore{"IYotoSession.TryRestoreAsync"} - restore -->|stored token works| lib["Library loads"] - restore -->|no session| settings["Settings page: enter client id, sign in"] - mcp --> silent["TryRestoreAsync (no browser)"] - silent --> stdio["McpEntry serves tools over stdio"] -``` - -[`ServiceRegistration.Build`](../../src/OpenMyo.App/Composition/ServiceRegistration.cs) is the composition root. -It calls each project's `AddXxx()` ([Infrastructure](../../src/OpenMyo.Infrastructure/ServiceCollectionExtensions.cs), -[Yoto](../../src/OpenMyo.Yoto/ServiceCollectionExtensions.cs), [Claude](../../src/OpenMyo.Claude/ServiceCollectionExtensions.cs), -[Core](../../src/OpenMyo.Core/ServiceCollectionExtensions.cs), [Mcp](../../src/OpenMyo.Mcp/ServiceCollectionExtensions.cs)) -and registers the view models. Two details: - -- Almost everything is a **singleton**. The caches and shared in-flight loads only work - because there is one instance per process. -- Every `HttpClient` gets a `User-Agent`, because Yoto's media CDN returns 403 without one. - -**What happens at launch.** `MainViewModel.InitializeAsync` loads settings, then calls -[`IYotoSession.TryRestoreAsync`](../../src/OpenMyo.Core/Abstractions/IYotoSession.cs). If a stored refresh token still works, the sign-in state changes: -the shell opens the library and [`ScreenLinks`](../../src/OpenMyo.App/Composition/ScreenLinks.cs) loads it (see [Loading the library](#loading-the-library)). If not, the app opens on Settings so the user can enter a client id and sign in. - -**How the UI handles work and errors.** Every screen view model derives from -[`OperationViewModel`](../../src/OpenMyo.App/Screens/OperationViewModel.cs). Its `RunAsync(status, work)` -sets `IsBusy`, gives the work a `CancellationToken` wired to the Cancel button, and catches *all* -exceptions, showing the message in `Error`. This is the one deliberate catch-all in the codebase: -services below it throw, and the UI boundary reports. - -## Navigation - -The window is a narrow navigation rail (icons, titles as tooltips) and a content area. Rail entries are [`SidebarItem`](../../src/OpenMyo.App/Screens/Shell/SidebarItem.cs)s held by [`MainViewModel`](../../src/OpenMyo.App/Screens/Shell/MainViewModel.cs) -in two lists, `TopItems` (Library, Import) and `BottomItems` (Settings, pinned to the bottom). Selecting -one calls `MainViewModel.Navigate`, which sets `CurrentPage` to a page view model. [`MainWindow`](../../src/OpenMyo.App/Screens/Shell/MainWindow.axaml) shows -`CurrentPage` in a `ContentControl`, and its `Window.DataTemplates` choose the view for each view model -type. Page view models are singletons, so a page keeps its state when the user navigates away and back. - -```mermaid -flowchart TD - item["SidebarItem
(TopItems / BottomItems)"] -->|selected| sel["MainViewModel.SelectedItem"] - sel -->|Navigate| page["MainViewModel.CurrentPage
= page view model"] - page -->|ContentControl| tmpl["MainWindow.DataTemplates
view model type → view"] - tmpl --> view["Page view
(x:DataType = view model)"] -``` - - -Panels inside a page, such as the title clean-up panel or the icon picker, are child view models exposed -as properties of the page view model and embedded in the page view with `DataContext="{Binding …}"`. -Steps: [How to add a page to the navigation rail](../how-to.md#how-to-add-a-page-to-the-navigation-rail) and -[How to add a panel to an existing screen](../how-to.md#how-to-add-a-panel-to-an-existing-screen). - -## Commands - -Every button and menu item runs a command on a view model. The editor's **Re-pick Every Icon** menu item -shows the whole path: - -```xml - - -``` - -```csharp -// Screens/Editor/Commands/ChapterIconCommands.cs -[RelayCommand] -private Task RematchAllIconsAsync() => MatchIconsAsync(replaceExisting: true, useAi: false); -``` - -```mermaid -flowchart TD - click["MenuItem click"] --> path["Binding path from the view's DataContext:
PlaylistEditorViewModel.Icons → ChapterIconCommands"] - path --> cmd["RematchAllIconsCommand
(IAsyncRelayCommand, generated)"] - cmd --> method["RematchAllIconsAsync → MatchAsync"] - method --> run["IChapterEditor.RunAsync
= OperationViewModel.RunAsync (busy, Cancel, errors)"] - run --> assign["IconAutoAssigner.MatchIconsAsync"] - assign --> apply["IChapterEditor.ApplyChapters
(shown as unsaved edits)"] -``` - -How the pieces fit: - -1. **The name is generated.** `[RelayCommand]` on `RematchAllIconsAsync` makes a `RematchAllIconsCommand` - property at compile time: the generator drops `Async` and adds `Command`. The class must be `partial`. - Press F12 on the name to see the generated code. -2. **Async commands block double runs.** A method that returns `Task` becomes an `IAsyncRelayCommand`, - which reports `CanExecute = false` while it runs, so the control greys out until the work finishes. -3. **`CanExecute` drives enabled state.** Save and Revert use `[RelayCommand(CanExecute = nameof(IsDirty))]`; - `[NotifyCanExecuteChangedFor]` on `_isDirty` re-checks them when it changes. -4. **Command groups keep view models small.** The editor exposes `Icons` ([`ChapterIconCommands`](../../src/OpenMyo.App/Screens/Editor/Commands/ChapterIconCommands.cs)), - `Batch` and `Cleanup` as properties, and the view binds through them (`Icons.…`, `Batch.…`). - -Why commands and not `Click` handlers: - -| | `Click` handler | Command | -|---|---|---| -| Lives in | View code-behind | View model | -| Enabled state | Set `IsEnabled` by hand | From `CanExecute`, and while an async command runs | -| Reuse | One control | Button, menu item and `KeyBinding` share one command | -| Testing | Needs a UI | Call `Execute` on the view model | - -`Click` and other events stay in code-behind only for view-only work (focus, drag-and-drop plumbing, -opening a picker), per CODESTANDARDS §8. References: -[Avalonia commanding](https://docs.avaloniaui.net/docs/input-interaction/commanding), -[events vs commands](https://docs.avaloniaui.net/docs/basics/user-interface/adding-interactivity), -[MVVM Toolkit source generators](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/generators/overview). - -## Loading the library - -```mermaid -sequenceDiagram - participant VM as LibraryViewModel - participant R as YotoPlaylistRepository - participant C as CardCache - participant Y as Yoto API - - VM->>R: ListAsync - R->>Y: GET content/mine - R-->>VM: Summaries (rows shown immediately) - loop Each card, 6 at a time - VM->>R: GetAsync(summary) - R->>C: Same updatedAt? - alt Cache hit - C-->>R: Card JSON - else Miss - R->>Y: GET content/{id} - R->>C: Store - end - R-->>VM: Playlist (row updates, filter counts update) - end - VM-->>VM: PlaylistsLoaded → library icons into the index -``` - -[`LibraryViewModel.RefreshAsync`](../../src/OpenMyo.App/Screens/Library/LibraryViewModel.cs) shows rows as -soon as the listing returns, then loads details in parallel and reports each result back to the UI thread through `Progress`. -Each [`PlaylistRowViewModel`](../../src/OpenMyo.App/Screens/Library/PlaylistRowViewModel.cs) gets its -[`PlaylistIssues`](../../src/OpenMyo.Core/Library/PlaylistIssues.cs) from -[`PlaylistHealth`](../../src/OpenMyo.Core/Library/PlaylistHealth.cs): no tracks, any chapter without an icon, -no cover. The filter chips above the list ([`FilterChipViewModel`](../../src/OpenMyo.App/Screens/Library/FilterChipViewModel.cs)) are just these flags: -"All" clears the filter, problem chips toggle and combine, and a row shows when it has every chosen issue -([`LibraryFilter.Matches`](../../src/OpenMyo.Core/Library/LibraryFilter.cs)). Each chip counts its own matches; problem chips at 0 fade out. -When every card is loaded, [`ScreenLinks`](../../src/OpenMyo.App/Composition/ScreenLinks.cs) feeds [`LibraryIcons.FromPlaylists`](../../src/OpenMyo.Core/Icons/LibraryIcons.cs) into [`IconIndexProvider`](../../src/OpenMyo.Core/Icons/IconIndexProvider.cs) (see [Where the indexed icons come from](icon-matching.md#where-the-indexed-icons-come-from)). - -Selecting several rows enables [`BulkActionsViewModel`](../../src/OpenMyo.App/Screens/Library/BulkActionsViewModel.cs) -(match missing icons across every selected playlist, and delete with a two-click confirm). The library -hands it `SelectedRows` and listens for its `RowsUpdated` and `RowsDeleted` events; it never holds the library. - -## Editing a playlist - -Selecting one row opens [`PlaylistEditorViewModel`](../../src/OpenMyo.App/Screens/Editor/PlaylistEditorViewModel.cs). -It keeps the loaded [`Playlist`](../../src/OpenMyo.Core/Playlists/Playlist.cs) as `_original` and shows its chapters as editable -[`ChapterRowViewModel`](../../src/OpenMyo.App/Screens/Editor/ChapterRowViewModel.cs)s. Any change (rename, -drag-reorder via [`DragReorder`](../../src/OpenMyo.App/Controls/DragReorder.cs), icon, delete) sets `IsDirty`. - -- **Save** rebuilds a `Playlist` from `_original` plus the rows (each row keeps its original chapter key), - calls `SaveAsync`, and shows the saved result. The Yoto client turns that into a patch of the raw card (see [Reading and saving cards](yoto-client.md#reading-and-saving-cards)). - -```mermaid -sequenceDiagram - participant E as PlaylistEditorViewModel - participant R as YotoPlaylistRepository - participant C as CardCache - participant K as CardComposer - participant Y as Yoto API - - E->>E: BuildPlaylist: _original + chapter rows - E->>R: SaveAsync(playlist) - R->>C: Last raw card JSON - alt Not cached - R->>Y: GET content/{id} - end - R->>K: Compose(raw, playlist): patch the clone - R->>Y: POST content - Y-->>R: Saved card - R->>C: Store - R-->>E: Saved playlist → Show, IsDirty = false -``` - -- **Revert** shows `_original` again. -- **Add tracks** and **Change cover** upload first and then save immediately through - [`PlaylistMediaService`](../../src/OpenMyo.Core/Publishing/PlaylistMediaService.cs). - -The editor's command groups live beside it in [`Screens/Editor`](../../src/OpenMyo.App/Screens/Editor): -[`ChapterIconCommands`](../../src/OpenMyo.App/Screens/Editor/Commands/ChapterIconCommands.cs) (auto-match, number, -open picker), [`ChapterBatchCommands`](../../src/OpenMyo.App/Screens/Editor/Commands/ChapterBatchCommands.cs) -(multi-select edits), [`TitleCleanupViewModel`](../../src/OpenMyo.App/Screens/Editor/TitleCleanupViewModel.cs) -(the rules in [Titles](import.md#titles) with a preview), and [`TrackSuggestionsViewModel`](../../src/OpenMyo.App/Screens/Editor/TrackSuggestionsViewModel.cs). -They reach the editor only through [`IChapterEditor`](../../src/OpenMyo.App/Screens/Editor/Commands/IChapterEditor.cs) -(run work, read the current playlist, apply changed chapters), which keeps the editor file small. -The icon picker is hidden until the user clicks a track's icon (`PickIconCommand`; `ClosePickerCommand` or Escape -hides it again). It also shows while it asks for an API key an AI action needs (`ShowPicker`). -[`ChapterSelection`](../../src/OpenMyo.App/Screens/Editor/ChapterSelection.cs) knows nothing about the picker: while it -is open, the editor points it at `Selection.Target` and, after each pick, calls `SelectNextWithoutIcon` -([`IconTargetSequence`](../../src/OpenMyo.App/Screens/IconPicker/IconTargetSequence.cs), shared with Import). - -## Images - -[`RemoteImageCache`](../../src/OpenMyo.App/Services/RemoteImageCache.cs) downloads each icon and cover URL once, -keeping bytes on disk and decoded bitmaps in memory. Concurrent requests for one URL share a download. -[`IconBitmapLoader`](../../src/OpenMyo.App/Services/IconBitmapLoader.cs) resolves a media id or -[`ArtworkSource`](../../src/OpenMyo.Core/Import/ArtworkSource.cs) to a bitmap. [`PixelImage`](../../src/OpenMyo.App/Controls/PixelImage.cs) draws 16×16 icons -scaled up without blurring. - -## Claude Desktop connector - -Settings → Claude Desktop ([`ClaudeDesktopViewModel`](../../src/OpenMyo.App/Screens/Settings/ClaudeDesktopViewModel.cs)) -writes an entry into Claude Desktop's config ([`ClaudeDesktopConfigFile`](../../src/OpenMyo.Infrastructure/ClaudeDesktop/ClaudeDesktopConfigFile.cs), -[`ConnectorConfigJson`](../../src/OpenMyo.Core/ClaudeDesktop/ConnectorConfigJson.cs)) that launches this same -executable with `--mcp`. Claude Desktop then starts OpenMyo as a background process and talks to it over -stdin/stdout. - - -```mermaid -sequenceDiagram - participant D as Claude Desktop - participant M as McpEntry (stdio) - participant T as Tool class (from DI) - participant G as ToolGuard - participant R as IPlaylistRepository - participant Y as Yoto API - - D->>M: Start "OpenMyo --mcp" - D->>M: tools/call set_track_icons - M->>T: ToolRegistry resolves the method's class - T->>G: RunAsync(body) - G->>T: Validate track range and icon ids - T->>R: GetAsync, then one SaveAsync - R->>Y: GET / POST content - T-->>D: Result with previous icons (for undo) - Note over G,D: Not signed in or network error → McpException with a plain sentence -``` - -- [`McpEntry`](../../src/OpenMyo.Mcp/McpEntry.cs) creates the server with fixed instructions describing the - intended workflow. -- [`ToolRegistry`](../../src/OpenMyo.Mcp/Support/ToolRegistry.cs) finds every `[McpServerTool]` method in the - assembly and resolves its class from DI on each call, so tools use the same singletons as the app. -- Tools: [`PlaylistTools`](../../src/OpenMyo.Mcp/Playlists/PlaylistTools.cs) (list, get), - [`PlaylistEditTools`](../../src/OpenMyo.Mcp/Playlists/PlaylistEditTools.cs) (rename playlist), - [`TrackEditTools`](../../src/OpenMyo.Mcp/Playlists/TrackEditTools.cs) (rename), - [`IconSearchTools`](../../src/OpenMyo.Mcp/Icons/IconSearchTools.cs) (search), - [`IconEditTools`](../../src/OpenMyo.Mcp/Icons/IconEditTools.cs) (set), - [`IconAutomationTools`](../../src/OpenMyo.Mcp/Icons/IconAutomationTools.cs) (auto-match, number). -- Tools that write **validate everything first** (track range, icon ids via - [`IconResolver`](../../src/OpenMyo.Mcp/Icons/IconResolver.cs)), then save once. They return the previous - titles or icons so Claude can undo. -- [`ToolGuard`](../../src/OpenMyo.Mcp/Support/ToolGuard.cs) turns "not signed in" and network errors into - plain MCP errors instead of stack traces. -- Sign-in is shared with the app through the secret store, and refreshes are coordinated by [`RefreshLock`](../../src/OpenMyo.Yoto/Auth/RefreshLock.cs) - (see [Sign-in and tokens](yoto-client.md#sign-in-and-tokens)). The connector never opens a browser: if there is no session, tools say "open OpenMyo and sign in". - -## Other platforms - -Avalonia can also target iOS, Android and the browser (WebAssembly), but OpenMyo builds only the desktop -head: [`Program`](../../src/OpenMyo.App/Program.cs) calls `UsePlatformDetect()` and -`StartWithClassicDesktopLifetime`, and the App project references `Avalonia.Desktop` only. - -Views, view models, commands and bindings would carry over unchanged. Each new platform needs its own -small entry-point project, and the shared UI would move out of `OpenMyo.App` into a library those -projects reference. Building for iOS needs a Mac. Core, Yoto and Claude are plain `net10.0` libraries. - -These parts assume a desktop and would need a replacement or would be left out: - -| Part | Desktop assumption | Web (WebAssembly) | iOS | -|---|---|---|---| -| Sign-in ([`LoopbackAuthorizer`](../../src/OpenMyo.Yoto/Auth/LoopbackAuthorizer.cs)) | Listens on `http://127.0.0.1:8787/callback` | No listener; redirect to the page itself | Use the system auth session with an app redirect URI | -| Secrets ([`SecretStoreFactory`](../../src/OpenMyo.Infrastructure/Secrets/SecretStoreFactory.cs)) | macOS Keychain or Windows DPAPI | No secure store in the browser | iOS Keychain | -| Import ([`IFilePickerService`](../../src/OpenMyo.App/Services/IFilePickerService.cs), [`TagLibAudioMetadataReader`](../../src/OpenMyo.Infrastructure/Audio/TagLibAudioMetadataReader.cs)) | Folder picker returning local paths | Picked files arrive as streams; no folders | Files app picks; sandboxed paths | -| Data and cache folders ([`AppPaths`](../../src/OpenMyo.Infrastructure/Paths/AppPaths.cs)) | Application Support / LocalAppData | Browser storage only | App sandbox folders | -| Claude Desktop connector (`--mcp`) | A second process on stdio | Not possible | Not possible | -| Calls to Yoto, yotoicons.com and Anthropic | Direct HTTPS | Only if each service allows cross-origin requests (not checked) | Direct HTTPS | -| Keyboard shortcuts, hover, drag-reorder | Mouse and keyboard | Works | Needs touch alternatives | - -References: [Avalonia supported platforms](https://docs.avaloniaui.net/docs/supported-platforms), -[dealing with platforms](https://docs.avaloniaui.net/docs/guides/building-cross-platform-applications/dealing-with-platforms). diff --git a/docs/design/icon-matching.md b/docs/design/icon-matching.md deleted file mode 100644 index 06602c5..0000000 --- a/docs/design/icon-matching.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -description: "Explanation of icon matching: word normalising, trigram scoring, suggestions, number icons, Claude keywords and community icons; read when icon results look wrong or matching changes." ---- - -# Icon matching - -The goal: given a track title such as *"It Began with a Rabbit's Foot"*, find the best 16×16 icon among -thousands, for free, offline, deterministically. Claude is an optional extra (see [Search with AI](#search-with-ai)). - -## Turning text into words - -[`TextNormalizer.Keywords`](../../src/OpenMyo.Core/Text/TextNormalizer.cs) is used on **both** sides (icon -titles and tags, and queries), so they compare like for like: - -- lower-case, accents stripped, anything that is not a letter or digit becomes a space; -- stop words dropped (`the`, `of`, `track`, `chapter`, `episode` …), as are single characters and pure numbers; -- plurals singularised (`stars` → `star`, `foxes` → `fox`, `berries` → `berry`). - -Two word lists in Core tune matching. Both are embedded text files you can edit without touching code: - -- [`WeakWords.txt`](../../src/OpenMyo.Core/Text/WeakWords.txt): words that rarely describe a picture (verbs, - filler, `little`, `bonus`). They still count, at weight **0.25** instead of 1. -- [`Synonyms.txt`](../../src/OpenMyo.Core/Text/Synonyms.txt): `head: related, words`, e.g. - `trivia: question, quiz, brain, bulb`, so a title can match an icon tagged with a related word. - -## Trigram similarity - -[`Trigrams`](../../src/OpenMyo.Core/Text/Trigrams.cs) works like PostgreSQL's `pg_trgm`. A word is padded as -`" word "` and cut into overlapping three-character windows. Similarity is shared ÷ total distinct (Jaccard): - -```text -star → " s" " st" "sta" "tar" "ar " (5) -start → " s" " st" "sta" "tar" "art" "rt " (6) -shared 4, total distinct 7 → similarity 0.57 -``` - -This tolerates plurals, typos and word forms without a dictionary. Trigrams are packed into `long`s and -kept sorted, so comparing two words is one linear merge. - -## The index and the score - -[`IconIndex`](../../src/OpenMyo.Core/Icons/IconIndex.cs) is built once from a list of -[`DisplayIcon`](../../src/OpenMyo.Core/Icons/DisplayIcon.cs)s: - -- Each icon gets terms ([`IconTerm`](../../src/OpenMyo.Core/Icons/IconTerm.cs)): its title words at weight - 1.0 and tag words at 0.9 (tags are broader). -- An inverted index maps each trigram to the icons that have it. A search only scores icons sharing at - least one trigram with the query (or a synonym), not the whole catalog. - -[`IconScorer`](../../src/OpenMyo.Core/Icons/IconScorer.cs) scores one icon against the query words: - -1. For each query word, take its **best** similarity against the icon's terms: - exact word = 1.0, synonym = 0.8, else the trigram similarity; times the term weight. -2. A best below **0.4** counts as 0, so `star` vs `start` (0.57) counts but random overlaps do not. -3. The score is the **weighted average** over query words (weak words weigh 0.25). - -So icons that match *more* of the subject words win, and filler words barely move the score. -Example: for `Twinkle Twinkle Little Star` against an icon titled `Star` with no tags, the words are -`twinkle` (1), `little` (0.25, weak) and `star` (1). Only `star` matches, so the score is -(0 + 0 + 1) ÷ 2.25 ≈ 0.44. Ties are broken by the shorter icon title. - -`IconIndex` also exposes `Vocabulary` (the 1,500 most common icon words, used in the Claude prompt) and -`Number(n)` (Yoto's own icon for a digit, see [From titles to assigned icons](#from-titles-to-assigned-icons)). - -## Where the indexed icons come from - -[`IconIndexProvider`](../../src/OpenMyo.Core/Icons/IconIndexProvider.cs) builds the shared index from: - -- [`IIconCatalog`](../../src/OpenMyo.Core/Abstractions/IIconCatalog.cs): Yoto's public icons (cached on disk for 7 days, stale copy used when offline) plus the - user's own uploads (memory only) ([`YotoIconCatalog`](../../src/OpenMyo.Yoto/Icons/YotoIconCatalog.cs)); -- **library icons** ([`LibraryIcons`](../../src/OpenMyo.Core/Icons/LibraryIcons.cs)): every icon already used - in the user's playlists. Many are not in the public catalog, so the titles of the chapters they were used - on become their tags. Searching `connie` then finds the icon already used for Connie episodes. - -When both know an icon, the catalog entry wins (its tags are curated). The index is rebuilt lazily after -`Invalidate()`, which is called whenever an icon is uploaded, and after each library load. - -## From titles to assigned icons - -Three entry points use the index: - -**Import suggestions** ([`IconSuggester`](../../src/OpenMyo.Core/Icons/IconSuggester.cs)): each title is -searched as-is for up to 12 candidates. A track whose best score is under **0.75** is "unsure". If the -request opted into AI (the import screen does not), only the unsure titles go to Claude, and its keywords' -matches rank ahead of the title's. A track with no matches at all falls back to matches for the playlist -title. - -**Auto-match in the editor and MCP** ([`IconAutoAssigner`](../../src/OpenMyo.Core/Icons/IconAutoAssigner.cs)): - -1. Skips chapters that already have an icon, unless "replace existing" is on. -2. Finds **series words** ([`SeriesWords`](../../src/OpenMyo.Core/Text/SeriesWords.cs)): words in at least half - of the titles (with 4 or more titles). They name the show, not the episode, so they are ignored. -3. Reduces each title to its subject ([`IconQuery`](../../src/OpenMyo.Core/Text/IconQuery.cs)): strips - numbering, bracketed asides, `Part 2`, a leading `Bonus!`, weak words and series words. - `It Began with a Rabbit's Foot` → `Rabbit's Foot`. -4. Runs `IconSuggester` on those queries. -5. Asks the community fallback (see [Community icons](#community-icons-yotoiconscom)) for any title where yotoicons.com scores better than Yoto's best. -6. Sets the winner on each chapter and its tracks. Nothing is saved; the caller saves. - - -```mermaid -flowchart TD - titles["Chapter titles"] --> skip{"Already has an icon?"} - skip -->|yes, replace off| keep["Leave as is"] - skip -->|no| series["SeriesWords: drop words in ≥ half the titles"] - series --> query["IconQuery: strip numbering, asides,
Part n, Bonus!, weak words"] - query --> suggest["IconSuggester: IconIndex search"] - suggest --> community{"yotoicons.com scores better?"} - community -->|yes| comm["Community icon"] - community -->|no| yoto["Best Yoto / library icon"] - comm --> set["Set on chapter and its tracks
(caller saves)"] - yoto --> set -``` - -**Number icons** ([`NumberIconMaker`](../../src/OpenMyo.Core/Icons/NumberIconMaker.cs)): track *n* gets -an icon showing *n*. Yoto's own number icon is used when it exists ([`NumberIcons`](../../src/OpenMyo.Core/Icons/NumberIcons.cs)); -otherwise [`NumberIconPainter`](../../src/OpenMyo.Core/Icons/NumberIconPainter.cs) draws a 16×16 PNG -([`PngWriter`](../../src/OpenMyo.Core/Icons/PngWriter.cs)) and uploads it with a recognisable title, so later -runs find it in the user's icons instead of uploading again. Supports 1–999. - -## Search with AI - -Claude never sees icon ids and never chooses an icon. It only suggests 1–3 *drawable keywords* for a title, -which are then matched locally like any other search. - -- [`AiIconSearch`](../../src/OpenMyo.Core/Icons/AiIconSearch.cs) runs only when the user clicks the button in - the [icon picker](../../src/OpenMyo.App/Screens/IconPicker/IconPickerViewModel.cs) and caches answers per title - for the session. -- [`ClaudeKeywordGenerator`](../../src/OpenMyo.Claude/ClaudeKeywordGenerator.cs) sends the title plus the - index vocabulary ([`KeywordPrompt`](../../src/OpenMyo.Claude/KeywordPrompt.cs)), so Claude picks words that - actually exist on icons. The system prompt is prompt-cached, effort is `low`, output is constrained to a - JSON schema and parsed by [`KeywordResponse`](../../src/OpenMyo.Claude/KeywordResponse.cs), and `max_tokens` - is 1,024 + 48 per title. -- The model comes from Settings (default `claude-opus-5-5`). The API key comes from [`ISecretStore`](../../src/OpenMyo.Core/Abstractions/ISecretStore.cs). -- If there is no key, or the call fails, matching carries on with trigrams only. - -## Community icons (yotoicons.com) - -yotoicons.com is a free community site with many more icons than Yoto's catalog. To keep searches local -and the load on the site low, OpenMyo downloads its whole listing once and searches it offline: - -- [`CommunityCatalogHarvester`](../../src/OpenMyo.Core/CommunityIcons/CommunityCatalogHarvester.cs) reads - page 1 to learn the total, then all other pages **4 at a time**, retrying each twice. Pages that still fail - are skipped and the catalog is marked incomplete. Pages are parsed by - [`YotoIconsListingParser`](../../src/OpenMyo.Core/CommunityIcons/YotoIconsListingParser.cs). -- [`CommunityCatalogProvider`](../../src/OpenMyo.Core/CommunityIcons/CommunityCatalogProvider.cs) loads the - saved catalog when it is under 7 days old, otherwise harvests. All callers share one in-flight load. - An incomplete catalog is used but harvested again on the next launch. -- [`CommunityCatalogIndex`](../../src/OpenMyo.Core/CommunityIcons/CommunityCatalogIndex.cs) reuses - [`IconIndex`](../../src/OpenMyo.Core/Icons/IconIndex.cs), and for automatic matching multiplies the score by *focus* (how much of the icon's own - wording the title matched). A focused `fence` icon beats a song-lyric icon that happens to contain "fence". - Ties go to the most downloaded icon. -- [`CommunityIconFallback`](../../src/OpenMyo.Core/Icons/CommunityIconFallback.cs) uses a community icon only - when it scores at least **0.15** and beats Yoto's best for that title by 0.01 (ties go to Yoto, since its - icons need no upload). If the site is unreachable, it returns nothing rather than failing. -- [`CommunityIconImporter`](../../src/OpenMyo.Core/CommunityIcons/CommunityIconImporter.cs) downloads the - chosen PNG and uploads it as the user's own icon, at most once per icon per run. diff --git a/docs/design/import.md b/docs/design/import.md deleted file mode 100644 index 93d57cb..0000000 --- a/docs/design/import.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -description: "Explanation of bulk import: grouping, track order, title cleaning, artwork and publishing; read when changing how files become playlists." ---- - -# Bulk import - -The user drops folders or files on [`ImportViewModel`](../../src/OpenMyo.App/Screens/Import/ImportViewModel.cs). -[`DraftBuilder`](../../src/OpenMyo.Core/Import/DraftBuilder.cs) turns them into -[`PlaylistDraft`](../../src/OpenMyo.Core/Import/PlaylistDraft.cs)s with no network access. Then the import -screen asks for icon suggestions, the user reviews, and [`PlaylistPublisher`](../../src/OpenMyo.Core/Publishing/PlaylistPublisher.cs) -uploads and creates each playlist. - -```mermaid -sequenceDiagram - participant VM as ImportViewModel - participant D as DraftBuilder - participant S as IconSuggester - participant P as PlaylistPublisher - participant Up as IMediaUploader - participant R as IPlaylistRepository - - VM->>D: BuildAsync(paths) - D->>D: Group → read tags → order → clean titles → find artwork - D-->>VM: Drafts - VM->>S: SuggestAsync(track titles) - S-->>VM: Best icon per track - Note over VM: User reviews titles, order, icons - VM->>P: PublishAsync(draft) - loop Each track, up to MaxParallelUploads - P->>Up: Upload audio (+ icon art if no icon chosen) - end - P->>Up: Upload cover - P->>R: SaveAsync(new playlist) -``` - -## Importing from a podcast feed - -The **From Feed…** dialog ([`FeedImportViewModel`](../../src/OpenMyo.App/Screens/Import/Feed/FeedImportViewModel.cs)) previews before anything downloads: - -1. [`FeedUrl`](../../src/OpenMyo.Core/Feeds/FeedUrl.cs) accepts http(s) links, `feed://`/`itpc://` subscribe links and bare - addresses. A link pasted anywhere on the import screen opens the dialog with it. -2. [`FeedParser`](../../src/OpenMyo.Core/Feeds/FeedParser.cs) reads RSS 2.0 with the iTunes extensions. Only items with an audio - enclosure count. Episodes are put oldest first, by `pubDate` when every item has one, otherwise in - reverse feed order. DTDs and external entities are never resolved. -3. The user ticks episodes (latest 100 ticked; more than 100 can't be downloaded) and can narrow the list with - [`EpisodeFilter`](../../src/OpenMyo.Core/Feeds/EpisodeFilter.cs): a minimum and maximum length (episodes with no - length in the feed pass), words to exclude and words a title must contain. Filtered-out episodes are hidden - and unticked. One [`EpisodeOrder`](../../src/OpenMyo.Core/Feeds/EpisodeOrder.cs) toggle sets both the list order - and the track order on the card (oldest first by default). -4. [`FeedImporter`](../../src/OpenMyo.Core/Feeds/FeedImporter.cs) downloads them in parallel (the **Feed episodes downloaded at the same time** setting, `AppSettings.MaxParallelDownloads`, default 6, at most 8; each row in the preview shows its own progress) into - `/FeedDownloads//001.mp3 …`, and the show artwork as `cover.` (type sniffed from the bytes; - a broken image link only loses the cover). It builds the draft directly, not through `DraftBuilder`: the - feed's order and titles are more reliable than podcast tags. Titles still go through `TitleCleaner`, the - show title becomes the playlist title and its artwork the cover. -5. The draft joins the import screen like any other. Its folder is deleted when the draft is published, - discarded or cleared; anything left behind (a crash, the app closed) is swept after two days on the next - feed download. - -## Which files become which playlist - -[`ImportGrouper`](../../src/OpenMyo.Core/Import/ImportGrouper.cs): - -- Dropped folders are expanded recursively to audio files ([`MediaTypes`](../../src/OpenMyo.Core/Import/MediaTypes.cs)); - hidden files are skipped. -- **Every folder that directly holds audio becomes one playlist.** -- **Disc folders merge into their parent.** A folder named like `CD1`, `Disc 2` or `disk_03` belongs to the - folder above it, so a two-CD audiobook becomes one playlist. - -## Track order - -[`TrackOrderer`](../../src/OpenMyo.Core/Import/TrackOrderer.cs) sorts by disc first (disc tag, else the `CD 2` -folder number, else 1). Within a disc it uses the most trustworthy signal that **every** file has: - -1. Track-number tags, but only if all files have one and no two clash on the same disc. -2. Otherwise, a leading number in every file name (`01 …`, `Track 3`, `2-05 …`). -3. Otherwise, natural file-name order ([`NaturalStringComparer`](../../src/OpenMyo.Core/Text/NaturalStringComparer.cs), - so `2` sorts before `10`). - -"All or nothing" matters: mixing tagged and untagged files would interleave them. - -## Titles - -[`DraftBuilder`](../../src/OpenMyo.Core/Import/DraftBuilder.cs) picks the raw title for each track: the tag title, unless it is empty or a placeholder like -`Track 01`, in which case the file name. The playlist title is the album tag if every track agrees on it, -otherwise the folder name. - -[`TitleCleaner.CleanAll`](../../src/OpenMyo.Core/Text/TitleCleaner.cs) then cleans the whole list together. -Each rule can be switched off in [`TitleCleanupOptions`](../../src/OpenMyo.Core/Text/TitleCleanupOptions.cs) -(the editor's clean-up panel exposes them). In order: - -| Rule | Example | -|---|---| -| Separators: `_`, `%20`, and dots when there are no spaces; web addresses removed | `my.song.name` → `my song name` | -| Noise in brackets: `(Official Audio)`, `(Lyrics)`, `[320 kbps]`, `(Remastered)` … | | -| Anything in `[square brackets]` (download ids) | `Song [x7Gh2]` → `Song` | -| Numbering: `CD1 `, `1-03 `, `03 - `, `Track 3.` | | -| Bare leading number: always if zero-padded (`01 Song`), otherwise only when **every** title starts with a digit | keeps `99 Red Balloons` in a normal list | -| ALL CAPS or all lower case → Title Case (only when more than 3 letters) | | -| User find/replace | | -| A shared `Artist - ` prefix on every title is removed | | - -If cleaning leaves nothing, the raw title is kept. Results are cut to 140 characters. -`TitleCleanupOptions.SuitedTo` turns off the bracket rule when at least 80% of titles start with `[`, -because then `[051] Connie` is the user's own numbering, not junk. - -## Artwork - -[`ArtworkLocator`](../../src/OpenMyo.Core/Import/ArtworkLocator.cs) returns -[`ArtworkSource`](../../src/OpenMyo.Core/Import/ArtworkSource.cs)s (a file, or "the picture embedded in this -audio file"). Nothing is read until publishing. - -- **Cover**: an image named `cover`, `folder`, `front`, `album`, `albumart` or `artwork`; else the only - image in the folder that is not a track sidecar; else the first embedded picture. -- **Per-track icon art**: an image with the same base name as the audio file (`03 Owl.mp3` + `03 Owl.png`). - Embedded pictures count only when tracks carry *different* pictures; identical embedded art is the album - cover, not an icon. - -## Publishing - -[`PlaylistPublisher`](../../src/OpenMyo.Core/Publishing/PlaylistPublisher.cs): - -- Uploads tracks in parallel, `MaxParallelUploads` at a time (setting, clamped to 1–8). Results go into a - fixed array by index, so parallelism never changes the order. -- For each track, the icon is the chosen one ([`TrackDraft.IconMediaId`](../../src/OpenMyo.Core/Import/TrackDraft.cs)). - If none was chosen, the icon art from 5.4 is uploaded as a custom icon; if there is none, the track has no icon. -- [`UploadProgressTracker`](../../src/OpenMyo.Core/Publishing/UploadProgressTracker.cs) combines per-file - progress into one bar. -- Each track becomes one chapter with one track, keys `01`, `02`, … Cover is uploaded, then one `SaveAsync` - creates the card. -- `AppendAsync` does the same for "Add tracks" in the editor, numbering after the existing chapters. - [`PlaylistMediaService`](../../src/OpenMyo.Core/Publishing/PlaylistMediaService.cs) runs added files through - the same [`DraftBuilder`](../../src/OpenMyo.Core/Import/DraftBuilder.cs) so they are cleaned and ordered like an import. diff --git a/docs/design/players.md b/docs/design/players.md deleted file mode 100644 index 213a49f..0000000 --- a/docs/design/players.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -description: "Explanation of track search and playing on Yoto players: how search matches, the output picker, MQTT control, connection lifecycle and safety defaults; read when changing search or player control." ---- - -# Track search and Yoto players - -## Searching tracks - -The library search field matches playlist titles and track titles together. The library already loads every -playlist's chapters in the background (from the `updatedAt` card cache), so search makes no extra requests. - -- `SearchQuery` splits the text into words. A title matches when it contains every word, ignoring case and - accents (`CompareOptions.IgnoreCase | IgnoreNonSpace`), and returns the matched ranges for highlighting. -- `TrackSearch.Match` checks the playlist title and each chapter title. A chapter is a track to the user, - so the 1-based chapter position is the track number shown. -- Playlists whose title matches come first, then those that match only on tracks. A row lists up to three - matching tracks. Clicking one opens the playlist with that track selected and scrolled into view. -- Searching while details are still loading inserts newly matching rows in place, rather than rebuilding the - list, so the playlist open in the editor keeps its unsaved edits. The summary line says how many playlists - are still being checked, so an incomplete result isn't mistaken for "no results". -- The MCP tool `search_tracks` uses the same matching. - -## Playing on a Yoto player - -The output button sits in the lower-right of the now-playing bar. Its menu lists **This computer** and every -player on the account; offline players are dimmed. It works like choosing a speaker on a phone: - -- **Changing the output never changes what a player is doing.** If the app itself is playing, that moves - to the chosen player at the same track and position, but only when the player is idle. A player that is - already playing or paused carries on, and the bar shows it with a notice. Each ▶ after that plays on that - player. -- **Players already playing show in the bar** from sign-in, one line each ("Kitchen Yoto · The Gruffalo · - 1:23 / 4:00") with pause/resume, volume and **Control**. Control makes that player the output without - touching what it plays. ▶ on a track still plays on the chosen output. (`LivePlayersViewModel`) -- Seeking happens only when the slider is let go (or an arrow key released). The slider also moves by itself - when a new track length arrives, and seeking is a `card/start`, so treating that as a seek restarted the - track in a loop. -- While a player is chosen, the bar stays visible, names the player and shows its live state, so it is - always clear where audio goes. -- **The choice is not saved.** Every launch starts on this computer, so opening the app never plays out loud - in another room unexpectedly. -- Files being imported exist only on this computer, so they always play locally (the bar says so). -- If the player stops answering, the app tries once more, then falls back to this computer with a notice. - -### Protocol - -| What | How | -|---|---| -| List players | `GET /device-v2/devices/mine` (`family:devices:view`) | -| Commands | MQTT publish to `device/{id}/command/card/start`, `card/pause`, `card/resume`, `card/stop`, `volume/set` | -| State | Subscribe to `device/{id}/data/events`. A message may carry only the fields that changed, so `PlayerState.Merge` folds each one into the previous state. | -| Broker | `wss://aqrphjqbp3u2z-ats.iot.eu-west-2.amazonaws.com/mqtt`, MQTT 3.1.1 over WebSockets | -| Auth | Username `?x-amz-customauthorizer-name=PublicJWTAuthorizer`, password = the access token (`family:devices:control`), client id `DASH` | - -Players report volume in steps (0–16) as `volume`, and their parental limit as `volumeMax`; the bar's slider -works in steps and stops at that limit. `volume/set` takes a percentage instead, so `PlayerMessages` -converts, rounding up so the player lands on the step asked for (step 10 is sent as 63%). - -`YotoPlayerRemote` turns off MQTTnet's packet fragmentation. AWS IoT closes the connection when an MQTT -packet arrives split across WebSocket frames. Subscribing still works with fragmentation on, so the fault -only shows when the first command is sent. - -`card/start` addresses the card by its short link, `https://yoto.io/`, plus `chapterKey`, -`trackKey` and `secondsIn`. Yoto has no "next" command, so next, previous and seeking are `card/start` -again with the neighbouring chapter or a new `secondsIn` (`PlayTargets`). - -### Connection lifecycle - -`YotoPlayerRemote` holds one shared `PlayerConnection` per player; the bar, the live list and commands all use -it: - -- From sign-in the app connects to every online player (re-listing every 2 minutes) so it can show ones - already playing. Watching only listens. Signing out closes every connection. -- Switching the output away from a player does not disconnect it; the live list keeps watching it. -- Yoto closes connections that are quiet for about five minutes, so the remote publishes `events/request` - every 295 s. That also asks the player for fresh state. -- The broker checks the token only when connecting. A dropped connection is reopened with a fresh token on - the next command. After an unexpected drop the connection waits 3 s and tries once more, then reports the - player as gone (the bar falls back to this computer; the live list drops its line). -- The client id is fixed per player, so only one connection per player can be open at a time. The Claude - Desktop tools run in a separate process and disconnect right after each command. That keeps any clash - with the app brief, and the app's reconnect recovers from it. - -Players report changes rather than a steady clock, so the bar ticks the position forward locally between -reports. diff --git a/docs/design/yoto-client.md b/docs/design/yoto-client.md deleted file mode 100644 index a90efc4..0000000 --- a/docs/design/yoto-client.md +++ /dev/null @@ -1,269 +0,0 @@ ---- -description: "Explanation of the Yoto client: card model, HTTP pipeline, sign-in and tokens, saving cards, uploads; read when changing anything that talks to Yoto." ---- - -# The Yoto client - -`OpenMyo.Yoto` is everything that speaks to Yoto: sign-in, the HTTP pipeline, reading and saving cards, -and uploading audio and images. It implements [`IPlaylistRepository`](../../src/OpenMyo.Core/Abstractions/IPlaylistRepository.cs), [`IMediaUploader`](../../src/OpenMyo.Core/Abstractions/IMediaUploader.cs) and [`IIconCatalog`](../../src/OpenMyo.Core/Abstractions/IIconCatalog.cs) -from Core. - -## The card model - -Everything OpenMyo does ends up as a change to a **card** on Yoto's `/content` API. A Make Your Own card -is one JSON document: - -```text -card -├─ cardId, title, updatedAt, … (plus fields OpenMyo does not model) -├─ metadata.cover.imageL cover image URL -└─ content.chapters[] what the player steps through - ├─ key "01", title, overlayLabel "1" - ├─ display.icon16x16 "yoto:#" the 16×16 pixel icon the player shows - └─ tracks[] - ├─ key "01", title - ├─ trackUrl "yoto:#" transcoded audio held by Yoto - └─ format, duration, fileSize, channels, display.icon16x16 -``` - -Properties of the Yoto model that shape the code: - -- **A chapter is what the user sees as "a track".** MYO cards normally have one track per chapter. - OpenMyo creates exactly that shape, and renaming a single-track chapter renames its track too - ([`Chapter.WithTitle`](../../src/OpenMyo.Core/Playlists/Chapter.cs)). Setting an icon sets it on the chapter - *and* each of its tracks ([`IconAutoAssigner.WithIcon`](../../src/OpenMyo.Core/Icons/IconAutoAssigner.cs)). -- **Icons are referenced by media id.** A media id is 43 URL-safe characters. Yoto's public icons and the - user's own uploads live in the same id space, so assigning an icon is just writing `yoto:#`. -- **Audio is referenced by content hash.** Uploading a file gives back `yoto:#`. -- **Saving is whole-document.** `POST /content` with a `cardId` replaces the card. There is no - per-field PATCH, so OpenMyo saves by patching the last-fetched document (see [Reading and saving cards](#reading-and-saving-cards)). -- **Titles are capped at 140 characters** ([`TitleCleaner.MaxTitleLength`](../../src/OpenMyo.Core/Text/TitleCleaner.cs)). - Yoto rejects the whole save for one over-long chapter title without saying which. - -The domain mirrors this as immutable records: [`Playlist`](../../src/OpenMyo.Core/Playlists/Playlist.cs) → -[`Chapter`](../../src/OpenMyo.Core/Playlists/Chapter.cs) → [`Track`](../../src/OpenMyo.Core/Playlists/Track.cs), -plus [`PlaylistSummary`](../../src/OpenMyo.Core/Playlists/PlaylistSummary.cs) for the cheap library listing. -Every edit produces a new record (`with { … }`); nothing mutates a playlist in place. - -## HTTP pipeline - -[`AddYoto`](../../src/OpenMyo.Yoto/ServiceCollectionExtensions.cs) registers three named clients -([`YotoHttpClients`](../../src/OpenMyo.Yoto/Http/YotoHttpClients.cs)): - -| Client | Base address | Handlers | Used for | -|---|---|---|---| -| `yoto-api` | `api.yotoplay.com` | [`RetryHandler`](../../src/OpenMyo.Yoto/Http/RetryHandler.cs) → [`YotoAuthHandler`](../../src/OpenMyo.Yoto/Auth/YotoAuthHandler.cs) | Every API call | -| `yoto-auth` | `login.yotoplay.com` | none | Token exchange and refresh | -| `yoto-upload` | none (presigned URLs) | none, no timeout | `PUT` of audio bytes to storage | - -A request on `yoto-api` goes through the handlers in order: - -1. `RetryHandler` retries **429 and 503** up to 3 attempts, waiting for `Retry-After` (capped at 30 s) or - 1 s × attempt. -2. `YotoAuthHandler` adds `Authorization: Bearer …`. On a **401** it asks the session for a new token once - and resends once. - - -```mermaid -sequenceDiagram - participant C as Caller (e.g. YotoPlaylistRepository) - participant R as RetryHandler - participant H as YotoAuthHandler - participant S as YotoSession - participant Y as api.yotoplay.com - - C->>R: Request on yoto-api - R->>H: Attempt 1 - H->>S: GetAccessTokenAsync - H->>Y: Request + Bearer token - alt 401 - Y-->>H: 401 - H->>S: RefreshAccessTokenAsync(rejected token) - H->>Y: Resend once with the new token - end - alt 429 or 503 - Y-->>R: 429 / 503 - R->>R: Wait Retry-After (max 30 s) or 1 s × attempt - R->>H: Attempt 2, then 3 - end - Y-->>C: Response (non-success → YotoApiException) -``` - -Both only resend when the body can be sent again ([`RequestContent.CanResend`](../../src/OpenMyo.Yoto/Http/RequestContent.cs)). -The upload client deliberately has no auth handler, so the bearer token never reaches the storage host. -Non-success responses become [`YotoApiException`](../../src/OpenMyo.Yoto/Http/YotoApiException.cs) via -[`YotoResponse`](../../src/OpenMyo.Yoto/Http/YotoResponse.cs). - -## Sign-in and tokens - -Each user registers their own public OAuth client at yoto.dev and pastes its id into Settings. There is no -client secret. Sign-in is Authorization Code + PKCE with a loopback redirect: - -```mermaid -sequenceDiagram - participant A as YotoSession - participant L as LoopbackAuthorizer (127.0.0.1:8787) - participant B as System browser - participant Y as Yoto login - participant S as ISecretStore - - A->>A: Pkce: verifier, challenge, state - A->>L: Start listening on /callback - L->>B: Open authorize URL - B->>Y: User signs in and approves - Y->>B: Redirect to /callback?code&state - B->>L: GET /callback - L-->>A: code (state checked) - A->>Y: YotoTokenClient: code + verifier - Y-->>A: access token, refresh token - A->>S: Store refresh token and granted scope -``` - -[`LoopbackAuthorizer`](../../src/OpenMyo.Yoto/Auth/LoopbackAuthorizer.cs) ignores requests whose `state` -does not match ([`AuthorizationCallback`](../../src/OpenMyo.Yoto/Auth/AuthorizationCallback.cs)) and gives up -after 5 minutes. [`Pkce`](../../src/OpenMyo.Yoto/Auth/Pkce.cs) makes the verifier, challenge and state; -[`YotoAuthEndpoints`](../../src/OpenMyo.Yoto/Auth/YotoAuthEndpoints.cs) holds the URLs and scope list. - -[`YotoSession`](../../src/OpenMyo.Yoto/Auth/YotoSession.cs) owns the tokens afterwards: - -- The **access token** lives only in memory. It is refreshed when it is within 60 s of expiry, or when a - request gets a 401. -- The **refresh token** lives in [`ISecretStore`](../../src/OpenMyo.Core/Abstractions/ISecretStore.cs). **Yoto refresh tokens are single-use:** each refresh - returns a new one, and the old one stops working. Two refreshes with the same token sign the user out. - So every refresh is serialised twice: - - within the process by a `SemaphoreSlim`; - - across processes (the app and the Claude Desktop connector can run at once) by - [`RefreshLock`](../../src/OpenMyo.Yoto/Auth/RefreshLock.cs), an exclusively opened file in the data - folder. The OS releases it if a process dies. - - The refresh token is read *inside* both locks, because the other process may have just replaced it. -- `RefreshAccessTokenAsync(rejectedToken)` only refreshes if the current token is still the rejected one. - So ten requests that all get a 401 cause one refresh, not ten. - -```mermaid -sequenceDiagram - participant H as Request needing a token - participant S as YotoSession - participant G as SemaphoreSlim (this process) - participant L as RefreshLock (file, all processes) - participant K as ISecretStore - participant Y as login.yotoplay.com - - H->>S: RefreshAccessTokenAsync(rejected) - S->>G: Wait - alt Another caller already refreshed - S-->>H: Current token (no refresh) - else Still the rejected token - S->>L: Acquire (waits for the app or connector) - S->>K: Read refresh token (inside both locks) - S->>Y: Refresh with that token - alt Success - Y-->>S: New access + new refresh token - S->>K: Store the new refresh token - else 400 / 401 / 403 - S->>K: Clear session → sign in again - end - S->>L: Release - end - S->>G: Release -``` - -- A 400/401/403 from the token endpoint clears the session (the user must sign in again). -- `TryRestoreAsync` also compares the stored scope with the current scope list. If the app now asks for - more scopes, the old token is dropped, because refreshing cannot widen a grant. - -## Reading and saving cards - -[`YotoPlaylistRepository`](../../src/OpenMyo.Yoto/Content/YotoPlaylistRepository.cs) implements -[`IPlaylistRepository`](../../src/OpenMyo.Core/Abstractions/IPlaylistRepository.cs): - -| Call | Request | Then | -|---|---|---| -| `ListAsync` | `GET content/mine` | [`CardMapper.ToSummary`](../../src/OpenMyo.Yoto/Content/CardMapper.cs) per card; cards with invalid ids are dropped | -| `GetAsync(summary)` | `GET content/{id}`, unless the cache has it | Raw JSON → `CardMapper.ToPlaylist` | -| `SaveAsync` | `POST content` | Response stored in the cache, mapped back | -| `DeleteAsync` | `DELETE content/{id}` | Removed from the cache | - -**Caching by `updatedAt`.** [`CardCache`](../../src/OpenMyo.Yoto/Content/CardCache.cs) keeps the last raw JSON -of every card, in memory and as `cache/cards/{id}.json`. `GetAsync` reuses it only when its `updatedAt` -equals the one in the fresh listing, so an unchanged library loads with one request. Disk failures are -ignored, since the cache is only an optimisation. - -**Saving without losing data.** Because saving replaces the whole card, rebuilding JSON from the domain -model would delete every field OpenMyo does not model (and Yoto adds fields over time). So a save -*patches* the last-fetched document instead: - -1. `SaveAsync` takes the cached raw card (or fetches it) as the base. -2. [`CardComposer`](../../src/OpenMyo.Yoto/Content/CardComposer.cs) deep-clones it, removes server-managed - fields (`createdAt`, `updatedAt`, `_id`, `userId`), checks title lengths, sets `title`, `cardId`, - `metadata.media.duration/fileSize` and the cover URL. -3. [`ChapterComposer`](../../src/OpenMyo.Yoto/Content/ChapterComposer.cs) rebuilds `content.chapters` in the - domain order: - - Each domain chapter **clones the raw chapter with the same `key`**, so unknown fields carry over. - Each raw item is used at most once. New chapters start empty. - - Keys are then **renumbered** (`01`, `02`, …) and the chapter `overlayLabel` set to the position. This is how - reordering works: the domain keeps the old key so the right raw node is found, and the save writes the - new position. - - Tracks follow the same rules, except that a track's `overlayLabel` counts tracks across the whole card - (1, 2, 3, … as in Yoto's examples) while its key restarts at `01` in each chapter. Media fields (`type`, `format`, `duration`, `fileSize`, `channels`) are - only written when the track is new or its `trackUrl` changed, so Yoto's own values are kept otherwise. - - Icons are written as `display.icon16x16 = "yoto:#"` only for a valid media id - ([`CardIds`](../../src/OpenMyo.Yoto/Content/CardIds.cs)); otherwise the field is removed. - - -```mermaid -flowchart TD - raw["Last-fetched raw card
(CardCache or GET)"] --> clone["CardComposer: deep clone,
drop createdAt / updatedAt / _id / userId"] - clone --> top["Set title, cardId,
duration, fileSize, cover"] - top --> ch["ChapterComposer: for each domain chapter,
clone raw chapter with the same key"] - ch --> renum["Renumber keys 01, 02 …
set overlayLabel, icons, new-track media"] - renum --> post["POST content"] - domain["Domain Playlist
(new order, titles, icons)"] --> top - domain --> ch -``` - -Reading is the mirror: `CardMapper` never mutates the document. A chapter without its own icon inherits -the first track icon it finds. - -## Uploading media - -[`YotoMediaUploader`](../../src/OpenMyo.Yoto/Media/YotoMediaUploader.cs): - -**Audio** (`UploadAudioAsync`): - -1. Hash the file with SHA-256. -2. `GET media/transcode/audio/uploadUrl?sha256=…`. Yoto returns an upload id and, *only if it has never - seen these bytes*, a presigned upload URL. Re-importing the same file skips the upload entirely. -3. `PUT` the file to the presigned URL on the `yoto-upload` client. - [`ProgressFileContent`](../../src/OpenMyo.Yoto/Media/ProgressFileContent.cs) reports bytes sent; upload is - shown as 90% of the progress bar. -4. Poll `media/upload/{id}/transcoded` (404 means "not yet") with backoff from 0.5 s to 2 s, for up to - 5 minutes ([`PollingPolicy`](../../src/OpenMyo.Yoto/Media/PollingPolicy.cs)). -5. Return `yoto:#` with the format, duration, size and channels Yoto reports. - - -```mermaid -sequenceDiagram - participant U as YotoMediaUploader - participant Y as Yoto API (yoto-api) - participant S as Storage (yoto-upload) - - U->>U: SHA-256 of the file - U->>Y: GET media/transcode/audio/uploadUrl?sha256 - Y-->>U: uploadId (+ uploadUrl only for new bytes) - opt Yoto has not seen these bytes - U->>S: PUT file (progress 0–90%) - end - loop Every 0.5–2 s, up to 5 min - U->>Y: GET media/upload/{id}/transcoded - Y-->>U: 404 = not yet, or transcoded result - end - U-->>U: yoto:#transcodedSha256 + format, duration, size, channels -``` - -**Cover**: `POST media/coverImage/user/me/upload` returns a public URL that goes in -`metadata.cover.imageL`. - -**Icon**: `POST media/displayIcons/user/me/upload?autoConvert=true` (Yoto scales it to 16×16) returns a -media id. The uploader then tells [`YotoIconCatalog`](../../src/OpenMyo.Yoto/Icons/YotoIconCatalog.cs) to forget the user's icon list so the new icon shows -up in searches. diff --git a/docs/how-to.md b/docs/how-to.md deleted file mode 100644 index a357e22..0000000 --- a/docs/how-to.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -description: "Step-by-step guides for common changes: Yoto calls, card fields, domain logic, settings, Claude Desktop tools, pages and panels; read when adding something new." ---- - -# How-to guides - -Every change also follows [CODESTANDARDS.md](../CODESTANDARDS.md) and passes the checks in -[CONTRIBUTING.md](../CONTRIBUTING.md#running-checks). - -## How to call a new Yoto endpoint - -1. Add request and response DTOs in [`Yoto/Json`](../src/OpenMyo.Yoto/Json) and register each type with a - `[JsonSerializable]` line on [`YotoJsonContext`](../src/OpenMyo.Yoto/Json/YotoJsonContext.cs). - Serialisation is source-generated, so an unregistered type fails at runtime. -2. Make the call in the class that owns the area: cards in [`YotoPlaylistRepository`](../src/OpenMyo.Yoto/Content/YotoPlaylistRepository.cs), media in - [`YotoMediaUploader`](../src/OpenMyo.Yoto/Media/YotoMediaUploader.cs), icons in [`YotoIconCatalog`](../src/OpenMyo.Yoto/Icons/YotoIconCatalog.cs). Create the client with - `httpClientFactory.CreateClient(YotoHttpClients.Api)` to get retries and auth, and read the response - with [`YotoResponse.ReadAsync`](../src/OpenMyo.Yoto/Http/YotoResponse.cs) or `EnsureSuccessAsync`. -3. Check any id from outside with [`CardIds`](../src/OpenMyo.Yoto/Content/CardIds.cs) before it goes into a URL, and escape query values. -4. If Core needs the feature, add a method to the Core interface (or a new interface in - [`Core/Abstractions`](../src/OpenMyo.Core/Abstractions)) and register the implementation in - [`AddYoto`](../src/OpenMyo.Yoto/ServiceCollectionExtensions.cs). -5. Test it with [`StubHttpHandler`](../tests/OpenMyo.Yoto.Tests/Support/StubHttpHandler.cs) in - [`tests/OpenMyo.Yoto.Tests`](../tests/OpenMyo.Yoto.Tests). -6. If it needs a new OAuth scope, add it to [`YotoAuthEndpoints.Scope`](../src/OpenMyo.Yoto/Auth/YotoAuthEndpoints.cs). Existing users are asked to sign in - again on next launch ([Sign-in and tokens](design/yoto-client.md#sign-in-and-tokens)). - -## How to store a new field on a card or chapter - -1. Add the property to the record in [`Core/Playlists`](../src/OpenMyo.Core/Playlists). -2. Read it in [`CardMapper`](../src/OpenMyo.Yoto/Content/CardMapper.cs). -3. Write it in [`CardComposer`](../src/OpenMyo.Yoto/Content/CardComposer.cs) or - [`ChapterComposer`](../src/OpenMyo.Yoto/Content/ChapterComposer.cs) by setting that one field on the - cloned node. Never build the node from scratch - ([Reading and saving cards](design/yoto-client.md#reading-and-saving-cards)). -4. Add a round-trip case to [`CardComposerTests`](../tests/OpenMyo.Yoto.Tests/Content/CardComposerTests.cs) - with the sample JSON in [`Samples`](../tests/OpenMyo.Yoto.Tests/Content/Samples.cs), and assert that an - unrelated field is still present after the save. - -## How to add domain logic - -A new title clean-up rule, library filter, matcher or similar. - -1. Put the logic in the feature folder under [`OpenMyo.Core`](../src/OpenMyo.Core) as a pure class or - static method. Take dependencies through Core interfaces only. -2. Register it in [`AddCore`](../src/OpenMyo.Core/ServiceCollectionExtensions.cs) if it has state or - dependencies. -3. Test it in the matching folder of [`tests/OpenMyo.Core.Tests`](../tests/OpenMyo.Core.Tests), using the - fakes in [`Fakes`](../tests/OpenMyo.Core.Tests/Fakes). -4. Call it from a view model ([How to add a page to the navigation rail](#how-to-add-a-page-to-the-navigation-rail), [How to add a panel to an existing screen](#how-to-add-a-panel-to-an-existing-screen)) or an MCP tool - ([How to add a Claude Desktop tool](#how-to-add-a-claude-desktop-tool)). - -Examples: - -- **Title clean-up rule:** a property on [`TitleCleanupOptions`](../src/OpenMyo.Core/Text/TitleCleanupOptions.cs) and a step in [`TitleCleaner.Clean`](../src/OpenMyo.Core/Text/TitleCleaner.cs). -- **Library filter:** a flag in [`PlaylistIssues`](../src/OpenMyo.Core/Library/PlaylistIssues.cs), a check in [`PlaylistHealth`](../src/OpenMyo.Core/Library/PlaylistHealth.cs), and a chip in - `LibraryViewModel.Chips` ([`LibraryViewModel`](../src/OpenMyo.App/Screens/Library/LibraryViewModel.cs)); matching and counts come from the flag. - -## How to add a setting or a secret - -**Setting** (anything not secret): - -1. Add an `init` property with a default to [`AppSettings`](../src/OpenMyo.Core/Abstractions/ISettingsStore.cs). - Existing `settings.json` files get the default. -2. Read it with [`ISettingsStore.LoadAsync`](../src/OpenMyo.Core/Abstractions/ISettingsStore.cs); save with `SaveAsync(current with { … })`. -3. Show it in [`SettingsViewModel`](../src/OpenMyo.App/Screens/Settings/SettingsViewModel.cs) and - [`SettingsView`](../src/OpenMyo.App/Screens/Settings/SettingsView.axaml). - -**Secret** (tokens, keys): - -1. Add a name to [`SecretNames`](../src/OpenMyo.Core/Abstractions/SecretNames.cs). -2. Read and write it through [`ISecretStore`](../src/OpenMyo.Core/Abstractions/ISecretStore.cs). Never put it in `AppSettings`, a log or a URL. - -## How to add a Claude Desktop tool - -1. Add a public method with `[McpServerTool(Name = "verb_noun", …)]` and a `[Description]` on the method - and each parameter, in a `[McpServerToolType]` class under [`Mcp/Playlists`](../src/OpenMyo.Mcp/Playlists) - or [`Mcp/Icons`](../src/OpenMyo.Mcp/Icons). Set `ReadOnly`, `Destructive` and `Idempotent` to match - what it does. -2. Wrap the body in [`ToolGuard.RunAsync`](../src/OpenMyo.Mcp/Support/ToolGuard.cs). Throw `McpException` with a plain sentence for bad input. -3. Load playlists through [`PlaylistLookup`](../src/OpenMyo.Mcp/Support/PlaylistLookup.cs), validate all - input before saving anything ([`TrackRange`](../src/OpenMyo.Mcp/Support/TrackRange.cs)), save once, and - return the previous values so Claude can undo. -4. Register a new tool class in [`AddMcpTools`](../src/OpenMyo.Mcp/ServiceCollectionExtensions.cs). - [`ToolRegistry`](../src/OpenMyo.Mcp/Support/ToolRegistry.cs) finds its methods by attribute. -5. Describe when to use it in the `Instructions` text in [`McpEntry`](../src/OpenMyo.Mcp/McpEntry.cs). -6. Test it with [`McpWorld`](../tests/OpenMyo.Mcp.Tests/McpWorld.cs) in - [`tests/OpenMyo.Mcp.Tests`](../tests/OpenMyo.Mcp.Tests). - -## How to add a page to the navigation rail - -A page is a full screen chosen from the navigation rail, like Import or Settings. The steps use a page called -`Reports`; replace the name with yours. - -1. **View model.** Create `src/OpenMyo.App/Screens/Reports/ReportsViewModel.cs`; the page's view goes beside - it. Derive from - [`OperationViewModel`](../src/OpenMyo.App/Screens/OperationViewModel.cs) if the page runs long work, and take services through the constructor. - - ```csharp - using CommunityToolkit.Mvvm.Input; - using OpenMyo.Core.Abstractions; - - namespace OpenMyo.App.Screens.Reports; - - public sealed partial class ReportsViewModel(IPlaylistRepository repository) : OperationViewModel - { - [RelayCommand] - private Task RefreshAsync() => RunAsync("Loading reports", async token => { /* … */ }); - } - ``` - -2. **View.** Create `src/OpenMyo.App/Screens/Reports/ReportsView.axaml` and its code-behind. Copy the shape of - [`SettingsView`](../src/OpenMyo.App/Screens/Settings/SettingsView.axaml): a `UserControl` with - `x:DataType` set, a `largeTitle` heading, and the error banner bound to `Error`. - - ```xml - - - - - - ``` - - ```csharp - using Avalonia.Controls; - - namespace OpenMyo.App.Screens.Reports; - - public sealed partial class ReportsView : UserControl - { - public ReportsView() => InitializeComponent(); - } - ``` - -3. **Register it** as a singleton in - [`ServiceRegistration`](../src/OpenMyo.App/Composition/ServiceRegistration.cs): - `services.AddSingleton();`. The container validates on build, so a missing - registration fails at start-up. - -4. **Map the view model to the view** in [`MainWindow.axaml`](../src/OpenMyo.App/Screens/Shell/MainWindow.axaml): - add one `xmlns` line next to the existing ones, then a `DataTemplate` in `Window.DataTemplates`. - - ```xml - xmlns:rep="using:OpenMyo.App.Screens.Reports" - … - - ``` - -5. **Add a rail icon**: a `StreamGeometry` (24×24 path) in - [`Styles/Theme.axaml`](../src/OpenMyo.App/Styles/Theme.axaml) next to `IconSettings`, for example - `x:Key="IconReports"`. - -6. **Add the destination** `Reports` to the `SidebarDestination` enum in - [`SidebarItem.cs`](../src/OpenMyo.App/Screens/Shell/SidebarItem.cs). - -7. **Hook it into the shell** in [`MainViewModel`](../src/OpenMyo.App/Screens/Shell/MainViewModel.cs): - - take `ReportsViewModel` in the constructor and expose it as a property; - - add `new("Reports", "IconReports", SidebarDestination.Reports)` to `TopItems` (or `BottomItems`); - - add `SidebarDestination.Reports => ReportsPage` to the switch in `Navigate`. - - `MainViewModel` has 4 constructor dependencies and the hard limit is 8. If the new page must react to - another page (for example refresh after an import), add that link to - [`ScreenLinks`](../src/OpenMyo.App/Composition/ScreenLinks.cs), not to either page. If more pages are - added later, group the page view models into one record (for example `ShellPages`) instead of adding - parameters. - -8. **Check it**: `dotnet build OpenMyo.sln`, run the app, click the new rail icon, and check the page - with the keyboard alone. - -## How to add a panel to an existing screen - -A panel is part of a screen, like the title clean-up panel in the editor or the icon picker beside the -import list. - -1. **View model.** Create it in the screen's folder, for example - `Screens/Editor/ChapterNotesViewModel.cs`. Derive from `ObservableObject`, like - [`TitleCleanupViewModel`](../src/OpenMyo.App/Screens/Editor/TitleCleanupViewModel.cs) and [`IconPickerViewModel`](../src/OpenMyo.App/Screens/IconPicker/IconPickerViewModel.cs). -2. **Expose it from the parent view model** as a read-only property: - - if it only needs the parent's state, create it in the parent's constructor, as - [`PlaylistEditorViewModel`](../src/OpenMyo.App/Screens/Editor/PlaylistEditorViewModel.cs) does with `Cleanup = new TitleCleanupViewModel(Chapters, Selection)`; - - if it needs services, register it in [`ServiceRegistration`](../src/OpenMyo.App/Composition/ServiceRegistration.cs) (`AddTransient` when each screen needs - its own instance, as with `IconPickerViewModel`) and take it in the parent's constructor. -3. **View.** Create `Screens/Editor/ChapterNotesView.axaml` as a `UserControl` with - `x:DataType="vm:ChapterNotesViewModel"`. -4. **Embed it** in the parent view, binding its `DataContext` to the property, as - [`PlaylistEditorView.axaml`](../src/OpenMyo.App/Screens/Editor/PlaylistEditorView.axaml) does: - - ```xml - - ``` - -5. **Check it**: build, run, and open the panel from the screen with the mouse and the keyboard. - -## How to render a screen without signing in - -[`tools/OpenMyo.Snapshots`](../tools/OpenMyo.Snapshots) renders the playlist editor headlessly with the real -styles and saves PNGs. Add a block there that opens your screen's view model, then run: - -```bash -dotnet run --project tools/OpenMyo.Snapshots -- [card json] -``` - -## How to improve icon matches - -1. Add the failing title as a test case in - [`IconAutoAssignerTests`](../tests/OpenMyo.Core.Tests/Icons/IconAutoAssignerTests.cs) or - [`IconQueryTests`](../tests/OpenMyo.Core.Tests/Text/IconQueryTests.cs). -2. Make the smallest change that fixes it, in this order of preference: - 1. A related word is missing: add a line to [`Synonyms.txt`](../src/OpenMyo.Core/Text/Synonyms.txt). - 2. A filler word is winning: add it to [`WeakWords.txt`](../src/OpenMyo.Core/Text/WeakWords.txt), - sorted, lower case, singular. - 3. Title noise reaches the query: extend [`IconQuery`](../src/OpenMyo.Core/Text/IconQuery.cs). - 4. Otherwise, change weights or thresholds in [`IconScorer`](../src/OpenMyo.Core/Icons/IconScorer.cs), [`IconSuggester`](../src/OpenMyo.Core/Icons/IconSuggester.cs) or [`CommunityIconFallback`](../src/OpenMyo.Core/Icons/CommunityIconFallback.cs). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..edd9743 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,49 @@ +--- +title: OpenMyo documentation +description: Learn how to use OpenMyo to import, tidy and play Yoto Make Your Own playlists, and how to contribute to its code. +ms.topic: overview +ms.date: 11/16/2026 +--- + +# OpenMyo documentation + +OpenMyo is an unofficial, open-source desktop app for macOS and Windows that manages Yoto "Make Your Own" +(MYO) playlists. These pages are split by audience: start under **Use OpenMyo** if you want to run the +app, or under **Contribute** if you want to change it. + +> [!NOTE] +> OpenMyo isn't affiliated with or endorsed by Yoto. Each user signs in with their own Yoto account and +> their own registered Yoto app. + +## Use OpenMyo + +| Get started | Work with playlists | Go further | +|---|---|---| +| [What is OpenMyo?](user/overview.md) | [Import folders of audio](user/import-folders.md) | [Use OpenMyo with Claude Desktop](user/use-with-claude-desktop.md) | +| [Quickstart: Sign in and run OpenMyo](user/quickstart.md) | [Import a podcast feed](user/import-podcast-feed.md) | [Where OpenMyo stores data](user/reference/data-locations.md) | +| [Build the app](user/build-the-app.md) | [Browse and search your library](user/library-and-search.md) | | +| | [Edit playlists](user/edit-playlists.md) | | +| | [Match icons](user/match-icons.md) | | +| | [Play audio here or on a Yoto player](user/play-audio.md) | | + +## Contribute + +| Understand the code | Change the code | Look things up | +|---|---|---| +| [Architecture overview](contribute/architecture/overview.md) | [Call a new Yoto endpoint](contribute/how-to/call-yoto-endpoint.md) | [Invariants](contribute/architecture/invariants.md) | +| [Cross-cutting concerns](contribute/architecture/cross-cutting-concerns.md) | [Store a new card field](contribute/how-to/add-card-field.md) | [Design decisions](contribute/reference/design-decisions.md) | +| [Card model](contribute/concepts/card-model.md) | [Add domain logic](contribute/how-to/add-domain-logic.md) | [Glossary](contribute/reference/glossary.md) | +| [Sign-in and tokens](contribute/concepts/sign-in-and-tokens.md) | [Add a setting or a secret](contribute/how-to/add-setting-or-secret.md) | | +| [Import pipeline](contribute/concepts/import-pipeline.md) | [Add a Claude Desktop tool](contribute/how-to/add-claude-desktop-tool.md) | | +| [Icon matching](contribute/concepts/icon-matching.md) | [Add a page to the navigation rail](contribute/how-to/add-navigation-page.md) | | +| [Claude Desktop connector](contribute/concepts/claude-desktop-connector.md) | [Add a panel to a screen](contribute/how-to/add-panel.md) | | +| [Yoto player control](contribute/concepts/yoto-player-control.md) | [Improve icon matches](contribute/how-to/improve-icon-matches.md) | | + +Every change follows [CODESTANDARDS.md](../CODESTANDARDS.md) and the workflow in +[CONTRIBUTING.md](../CONTRIBUTING.md). The full list of pages is in [toc.yml](toc.yml). + +## Related content + +- [OpenMyo on GitHub: README](../README.md) +- [Security policy](../SECURITY.md) +- [Yoto API reference](https://yoto.dev/api/) diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 0000000..99c1d69 --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,116 @@ +items: + - name: OpenMyo documentation + href: index.md + - name: Use OpenMyo + items: + - name: Overview + expanded: true + items: + - name: What is OpenMyo? + href: user/overview.md + - name: Quickstarts + items: + - name: Sign in and run OpenMyo + href: user/quickstart.md + - name: How-to guides + items: + - name: Build the app + href: user/build-the-app.md + - name: Import folders of audio + href: user/import-folders.md + - name: Import a podcast feed + href: user/import-podcast-feed.md + - name: Browse and search your library + href: user/library-and-search.md + - name: Edit playlists + href: user/edit-playlists.md + - name: Match icons + href: user/match-icons.md + - name: Play audio here or on a Yoto player + href: user/play-audio.md + - name: Use OpenMyo with Claude Desktop + href: user/use-with-claude-desktop.md + - name: Reference + items: + - name: Data locations + href: user/reference/data-locations.md + - name: Contribute + items: + - name: Architecture + items: + - name: Overview + href: contribute/architecture/overview.md + - name: Invariants + href: contribute/architecture/invariants.md + - name: Cross-cutting concerns + href: contribute/architecture/cross-cutting-concerns.md + - name: Concepts + items: + - name: Yoto client + items: + - name: Card model + href: contribute/concepts/card-model.md + - name: HTTP pipeline + href: contribute/concepts/yoto-http-pipeline.md + - name: Sign-in and tokens + href: contribute/concepts/sign-in-and-tokens.md + - name: Read and save cards + href: contribute/concepts/read-and-save-cards.md + - name: Media uploads + href: contribute/concepts/media-uploads.md + - name: Import + items: + - name: Import pipeline + href: contribute/concepts/import-pipeline.md + - name: Podcast feed import + href: contribute/concepts/podcast-feed-import.md + - name: Icons + items: + - name: Icon matching + href: contribute/concepts/icon-matching.md + - name: AI icon search + href: contribute/concepts/ai-icon-search.md + - name: Community icons + href: contribute/concepts/community-icons.md + - name: Desktop app + items: + - name: Start-up and composition + href: contribute/concepts/app-startup.md + - name: Navigation and commands + href: contribute/concepts/navigation-and-commands.md + - name: Library and editor + href: contribute/concepts/library-and-editor.md + - name: Claude Desktop connector + href: contribute/concepts/claude-desktop-connector.md + - name: Search and players + items: + - name: Track search + href: contribute/concepts/track-search.md + - name: Yoto player control + href: contribute/concepts/yoto-player-control.md + - name: How-to guides + items: + - name: Call a new Yoto endpoint + href: contribute/how-to/call-yoto-endpoint.md + - name: Store a new card field + href: contribute/how-to/add-card-field.md + - name: Add domain logic + href: contribute/how-to/add-domain-logic.md + - name: Add a setting or a secret + href: contribute/how-to/add-setting-or-secret.md + - name: Add a Claude Desktop tool + href: contribute/how-to/add-claude-desktop-tool.md + - name: Add a page to the navigation rail + href: contribute/how-to/add-navigation-page.md + - name: Add a panel to a screen + href: contribute/how-to/add-panel.md + - name: Render screens without signing in + href: contribute/how-to/render-screen-snapshots.md + - name: Improve icon matches + href: contribute/how-to/improve-icon-matches.md + - name: Reference + items: + - name: Design decisions + href: contribute/reference/design-decisions.md + - name: Glossary + href: contribute/reference/glossary.md diff --git a/docs/user/build-the-app.md b/docs/user/build-the-app.md new file mode 100644 index 0000000..92ef757 --- /dev/null +++ b/docs/user/build-the-app.md @@ -0,0 +1,45 @@ +--- +title: Build the app +description: Publish OpenMyo as a single file that runs without .NET installed, for Windows or macOS on Apple silicon or Intel. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Build the app + +There are no prebuilt downloads yet, so you build the app yourself. Each command makes one file that runs without .NET installed. + +## Prerequisites + +- The [.NET 10 SDK](https://dotnet.microsoft.com/download). +- A clone of the OpenMyo repository. + +## Publish + +1. From the repository root, run the command for your platform. The output goes to `publish/`. + + | Platform | Command | Output | + |---|---|---| + | Windows | `dotnet publish src/OpenMyo.App -c Release -r win-x64 -o publish` | `OpenMyo.exe` | + | macOS, Apple silicon | `dotnet publish src/OpenMyo.App -c Release -r osx-arm64 -o publish` | `OpenMyo` | + | macOS, Intel | `dotnet publish src/OpenMyo.App -c Release -r osx-x64 -o publish` | `OpenMyo` | + + You can build for either platform from either one. + +2. Open the result. On macOS, run it from Terminal (`./publish/OpenMyo`) or double-click it in Finder. + +## Things to know + +- On macOS the result is a plain executable, not an `.app` bundle. +- The builds aren't code-signed. Windows SmartScreen and macOS Gatekeeper warn the first time you open a copy downloaded from elsewhere. +- The first launch takes a few seconds longer while the app unpacks itself. + +## Use the built app with Claude Desktop + +Open the built app and choose **Settings** > **Connect to Claude Desktop**. Claude Desktop then launches that same file, so keep it where it is, or connect again after you move it. For details, see [Use OpenMyo with Claude Desktop](use-with-claude-desktop.md). + +## Related content + +- [Quickstart: Sign in and run OpenMyo](quickstart.md) +- [Use OpenMyo with Claude Desktop](use-with-claude-desktop.md) +- [Data and cache locations](reference/data-locations.md) diff --git a/docs/user/edit-playlists.md b/docs/user/edit-playlists.md new file mode 100644 index 0000000..9f9df81 --- /dev/null +++ b/docs/user/edit-playlists.md @@ -0,0 +1,56 @@ +--- +title: Edit a playlist +description: Rename tracks, reorder them, set the cover, tidy titles and rename every title with AI in the OpenMyo playlist editor. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Edit a playlist + +The playlist editor lets you rename tracks, drag to reorder, set the cover and pick icons. Hints point out what needs attention, and each is one click. + +## Prerequisites + +- You're signed in to Yoto and have at least one playlist. + +## Open a playlist and edit it + +1. In the library, open a playlist. +2. Rename tracks, drag them to reorder, and set the cover. +3. Select an icon to pick one. See [Match icons to tracks](match-icons.md). +4. Save your changes. + +## Use hints + +Hints such as "31 missing icons" or "Tidy 8 titles" only appear when they apply. Select a hint to act on it. + +## Edit several tracks at once + +Select several tracks to give them the same icon, number them or remove them. + +## Tidy titles + +1. Choose **Tidy Titles…**. +2. Switch each cleanup rule on or off, or add your own find and replace. +3. Check the preview, which shows the result before anything changes. +4. Apply the changes. + +Titles that follow a pattern on purpose, like "[051] Episode", are left alone. + +## Rename every title with AI + +> [!NOTE] +> This is optional and needs an Anthropic API key. See [Match icons to tracks](match-icons.md#set-up-claude-optional). + +1. In the editor's **⋯** menu, choose **Rename Every Title with AI**. Claude suggests a clean title for every track, with no track numbers, file-name leftovers or repeated album names. +2. Check the new titles. They show as unsaved edits. +3. Choose **Save**, or **Revert** to undo. + +Without an API key, a connected Claude Desktop gets the request instead and saves straight to Yoto. See [Use OpenMyo with Claude Desktop](use-with-claude-desktop.md). + +## Related content + +- [Match icons to tracks](match-icons.md) +- [Browse and search your library](library-and-search.md) +- [Play audio on your computer or a Yoto player](play-audio.md) +- [Library and editor](../contribute/concepts/library-and-editor.md) diff --git a/docs/user/import-folders.md b/docs/user/import-folders.md new file mode 100644 index 0000000..34c1d9d --- /dev/null +++ b/docs/user/import-folders.md @@ -0,0 +1,38 @@ +--- +title: Import folders of audio as playlists +description: Turn folders of audio files into Yoto MYO playlists with cleaned titles, ordered tracks, cover art and track icons. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Import folders of audio as playlists + +Use bulk import to turn folders or audio files into Yoto playlists. Each folder becomes one playlist, and OpenMyo cleans titles, orders tracks and finds artwork for you. + +## Prerequisites + +- You're signed in to Yoto. See [Quickstart: Sign in and run OpenMyo](quickstart.md). + +## Import folders + +1. Open the **Import** screen. +2. Choose, or drag in, folders or audio files. Each folder becomes a draft playlist. +3. Review each draft. To listen first, hover a track and select ▶. Import previews play your local files before anything is uploaded. +4. Choose **Create Playlists**. + +## What OpenMyo does for you + +**Titles.** Track numbers, underscores, "(Official Audio)"-style noise and repeated artist prefixes are removed from titles. To change the rules, see [Tidy titles](edit-playlists.md#tidy-titles). + +**Order.** Tracks are ordered by disc and track tags, then leading numbers, then name. + +**Cover art.** The cover comes from an image in the folder (`cover.jpg`, `folder.jpg`, and so on) or from art embedded in the audio. + +**Track icons.** A track gets an icon from an image with the same base name as its audio file. To match icons from titles instead, see [Match icons to tracks](match-icons.md). + +## Related content + +- [Import a podcast feed as a playlist](import-podcast-feed.md) +- [Edit a playlist](edit-playlists.md) +- [Play audio on your computer or a Yoto player](play-audio.md) +- [Import pipeline](../contribute/concepts/import-pipeline.md) diff --git a/docs/user/import-podcast-feed.md b/docs/user/import-podcast-feed.md new file mode 100644 index 0000000..d07fff9 --- /dev/null +++ b/docs/user/import-podcast-feed.md @@ -0,0 +1,40 @@ +--- +title: Import a podcast feed as a playlist +description: Preview a podcast feed, filter its episodes, and download them as a draft Yoto playlist named after the show. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Import a podcast feed as a playlist + +Turn episodes from a podcast feed into a Yoto playlist. OpenMyo downloads the episodes you pick and uses the show's artwork as the cover. + +## Prerequisites + +- You're signed in to Yoto. +- The link to the podcast's feed. + +## Import episodes + +1. On the **Import** screen, choose **From Feed…**. You can also paste a feed link anywhere on the screen. +2. Paste the feed link and choose **Preview** to list the episodes. The latest 100 are ticked, because a playlist holds up to 100 tracks. +3. Optional: narrow the list. + - **Length**: set from and to values, in minutes. + - **Exclude titles with**: for example `trailer, bonus`. + - **Only titles with**: keep only matching titles. + + Hidden episodes are never downloaded. +4. Set **Order** to oldest or newest first. This applies both to the list and to the card. +5. Change the ticks as needed, then choose **Download & Add**. + + The episodes download into a temporary folder and appear as a draft named after the show, with the show's artwork as its cover. +6. Review the draft like any other import. You can change the name and cover, then choose **Create Playlists**. + +> [!NOTE] +> The downloaded files are deleted once the playlist is created or the draft is discarded. + +## Related content + +- [Import folders of audio as playlists](import-folders.md) +- [Edit a playlist](edit-playlists.md) +- [Podcast feed import](../contribute/concepts/podcast-feed-import.md) diff --git a/docs/user/library-and-search.md b/docs/user/library-and-search.md new file mode 100644 index 0000000..bd10efa --- /dev/null +++ b/docs/user/library-and-search.md @@ -0,0 +1,40 @@ +--- +title: Browse and search your library +description: View your playlists as a list or grid, filter by missing icons or covers, search playlists and tracks, and act on several at once. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Browse and search your library + +The library shows your playlists as a list or a grid of covers. Use filters and search to find what needs attention, then act on several playlists together. + +## Prerequisites + +- You're signed in to Yoto. + +## Filter the library + +1. Open the library. +2. Switch between the list and the grid of covers. +3. Use the filter chips to show playlists with no tracks, missing icons or missing covers. + +## Run bulk actions + +1. Select several playlists. +2. Choose an action to match their icons or delete them together. For icon matching, see [Match icons to tracks](match-icons.md). + +## Search playlists and tracks + +1. Type in the library's search field. It finds playlists by title and tracks by title, across every playlist. +2. Read the results. Matching tracks are listed under their playlist with the matched words highlighted. +3. Select a track to open its playlist at that track, ready to play. + +Every word you type must appear, in any order, ignoring capitals and accents. For example, "gruff child" finds "The Gruffalo's Child". + +## Related content + +- [Edit a playlist](edit-playlists.md) +- [Play audio on your computer or a Yoto player](play-audio.md) +- [Library and editor](../contribute/concepts/library-and-editor.md) +- [Track search](../contribute/concepts/track-search.md) diff --git a/docs/user/match-icons.md b/docs/user/match-icons.md new file mode 100644 index 0000000..47401d6 --- /dev/null +++ b/docs/user/match-icons.md @@ -0,0 +1,55 @@ +--- +title: Match icons to tracks +description: Match track titles to Yoto icons for free, search community icons, and optionally use Claude to find better matches. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Match icons to tracks + +OpenMyo matches track titles to icons so each track on your player shows a picture. Matching is free and doesn't use AI. You can add community icons, and optionally ask Claude for more ideas. + +## Prerequisites + +- You're signed in to Yoto. +- For **Search with AI** only: an Anthropic API key. + +## Match icons for free + +OpenMyo compares each track title with the names and tags of Yoto's public icons, the icons already in your playlists and Yoto's number icons. If Yoto has nothing close, a strong match from [yotoicons.com](https://yotoicons.com) is added to your icons. + +1. Select one or more playlists in the library, or open a playlist in the editor. +2. Choose the icon matching action, or select a hint such as "12 missing icons". +3. Check the result. Select a track's icon to change it in the icon picker. + +## Search community icons + +The icon picker also searches yotoicons.com, credits the artist and adds the icon you choose to your Yoto account. + +The search runs against a copy of the catalog kept on your computer and updated automatically, so results appear as you type. Images are only downloaded when shown. + +## Set up Claude (optional) + +Icon matching works without Claude. To add **Search with AI** to the icon picker: + +1. Open **Settings**. +2. Turn on **AI Icon Search (optional)**. +3. Paste an API key from the Anthropic console into **Anthropic API key**. OpenMyo stores it in the Keychain or DPAPI, and the search runs as soon as the key is saved. +4. Optional: choose a different Claude model. + +> [!IMPORTANT] +> Claude never sees your audio, only track titles. + +## Search with AI + +1. In any icon picker, select **Search with AI**. Claude only runs when you click it. +2. Claude suggests a few words for that one title. OpenMyo matches them against the local icon index. +3. Pick an icon from the results. + +Answers are cached per title. In the editor's **⋯** menu, **Re-pick Every Icon with AI** asks Claude about titles the free matcher is unsure of. + +## Related content + +- [Edit a playlist](edit-playlists.md) +- [Use OpenMyo with Claude Desktop](use-with-claude-desktop.md) +- [Icon matching](../contribute/concepts/icon-matching.md) diff --git a/docs/user/overview.md b/docs/user/overview.md new file mode 100644 index 0000000..f2d54ac --- /dev/null +++ b/docs/user/overview.md @@ -0,0 +1,35 @@ +--- +title: OpenMyo overview +description: OpenMyo is an unofficial desktop app for macOS and Windows that manages Yoto Make Your Own playlists, titles and icons. +ms.topic: overview +ms.date: 11/16/2026 +--- + +# OpenMyo overview + +OpenMyo is an unofficial, open-source desktop app for managing Yoto "Make Your Own" (MYO) playlists on macOS and Windows. It imports folders of audio as playlists, cleans up track titles and matches icons. It searches every playlist for a track by title and can play any track on one of your Yoto players. Claude Desktop can also use it to rename tracks, pick icons, find tracks and play them on a player. + +> [!NOTE] +> OpenMyo isn't affiliated with or endorsed by Yoto. Each user signs in with their own Yoto account and their own registered Yoto app. + +## What you can do + +- **Import in bulk.** Choose or drag in folders or audio files, and each folder becomes a playlist. Titles are cleaned, tracks are ordered and artwork is found. See [Import folders of audio as playlists](import-folders.md). +- **Import a podcast feed.** Pick episodes from a feed and turn them into a playlist. See [Import a podcast feed as a playlist](import-podcast-feed.md). +- **Manage your library.** Browse playlists as a list or a grid of covers, filter by what's missing, search playlists and tracks, and act on several at once. See [Browse and search your library](library-and-search.md). +- **Edit playlists.** Rename tracks, drag to reorder, set the cover, tidy titles and pick icons. See [Edit a playlist](edit-playlists.md). +- **Match icons.** Match track titles to Yoto's public icons for free, or add community icons and optional AI search. See [Match icons to tracks](match-icons.md). +- **Play audio.** Listen to tracks on your computer or on a Yoto player. See [Play audio on your computer or a Yoto player](play-audio.md). +- **Work with Claude Desktop.** Let Claude rename playlists and tracks, pick icons, find tracks and play them. See [Use OpenMyo with Claude Desktop](use-with-claude-desktop.md). + +To install it, start with [Quickstart: Sign in and run OpenMyo](quickstart.md). + +## Privacy + +OpenMyo keeps your Yoto sign-in and API key in the macOS Keychain or encrypted with Windows DPAPI, never in settings files. Claude is optional, and it never sees your audio, only track titles. For where everything else is kept, see [Data and cache locations](reference/data-locations.md). + +## Related content + +- [Quickstart: Sign in and run OpenMyo](quickstart.md) +- [Build the app](build-the-app.md) +- [Architecture overview](../contribute/architecture/overview.md) diff --git a/docs/user/play-audio.md b/docs/user/play-audio.md new file mode 100644 index 0000000..749a70e --- /dev/null +++ b/docs/user/play-audio.md @@ -0,0 +1,45 @@ +--- +title: Play audio on your computer or a Yoto player +description: Preview tracks with the playback bar and media keys, or move playback to one of your Yoto players and control it. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Play audio on your computer or a Yoto player + +Listen to tracks in OpenMyo on your computer, or send them to a Yoto player. Playback keeps going while you move between screens. + +## Prerequisites + +- To play on a Yoto player: you're signed in to Yoto, and the player is online. + +## Play a track on your computer + +1. Hover a track in the playlist editor or on the **Import** screen and select ▶. The rest of the playlist plays after it. Import previews play your local files before anything is uploaded. +2. Use the bar along the bottom of the window: play/pause, previous, next, a position slider and volume. + +The keyboard's media keys and Cmd+Shift+Space (Ctrl+Shift+Space on Windows) also play and pause. + +## Play on a Yoto player + +1. While something plays, select the speaker button in the bottom-right corner of the bar. It lists **This computer** and your Yoto players. Offline players are greyed out. +2. Choose an idle player. What's playing here moves to it, at the same track and position. A player that's already playing carries on undisturbed. + +Until you switch back, every ▶ plays on that player. The bar shows its track, play/pause, next/previous, position and volume. + +## Control a player that's already playing + +Yoto players that are playing also show as a line each in the bar, with pause, volume and **Control**. **Control** makes that player the output without changing what it plays. + +> [!NOTE] +> OpenMyo always starts on **This computer**, so opening it never plays out loud in another room. + +## Sign in again for player control + +The first time after player control arrives, Yoto asks you to sign in once more to allow OpenMyo to control your players. + +## Related content + +- [Browse and search your library](library-and-search.md) +- [Use OpenMyo with Claude Desktop](use-with-claude-desktop.md) +- [Yoto player control](../contribute/concepts/yoto-player-control.md) diff --git a/docs/user/quickstart.md b/docs/user/quickstart.md new file mode 100644 index 0000000..96907ed --- /dev/null +++ b/docs/user/quickstart.md @@ -0,0 +1,44 @@ +--- +title: "Quickstart: Sign in and run OpenMyo" +description: Register a Yoto app, start OpenMyo with dotnet run and sign in with your Yoto account to see your playlists. +ms.topic: quickstart +ms.date: 11/16/2026 +--- + +# Quickstart: Sign in and run OpenMyo + +In this quickstart, you register your own Yoto app, start OpenMyo from source and sign in so your playlists appear. + +## Prerequisites + +- The [.NET 10 SDK](https://dotnet.microsoft.com/download). The exact version is pinned in `global.json`. +- macOS or Windows. +- A Yoto account. + +## Register an app at yoto.dev + +1. Go to and register an app as a **public client**. +2. Set the redirect URI to `http://127.0.0.1:8787/callback`. +3. Copy the app's client id. + +## Start the app + +From the repository root, run: + +```bash +dotnet run --project src/OpenMyo.App +``` + +## Sign in + +1. Open **Settings**. +2. Paste the client id into **Yoto client ID**. +3. Select **Sign In…**. OpenMyo opens your browser so you can sign in with Yoto and allow it to manage your playlists and play them on your Yoto players. Your password never passes through the app. + +When you're signed in, **Settings** shows **Signed in**. + +## Next steps + +- [Import folders of audio as playlists](import-folders.md) +- [Browse and search your library](library-and-search.md) +- [Build a standalone copy of the app](build-the-app.md) diff --git a/docs/user/reference/data-locations.md b/docs/user/reference/data-locations.md new file mode 100644 index 0000000..acd237d --- /dev/null +++ b/docs/user/reference/data-locations.md @@ -0,0 +1,42 @@ +--- +title: Data and cache locations +description: Where OpenMyo stores settings, secrets and cached data on macOS and Windows, and which folders are safe to delete. +ms.topic: reference +ms.date: 11/16/2026 +--- + +# Data and cache locations + +OpenMyo keeps small settings in a data folder and re-downloadable data in a cache folder. + +## Folders + +| | macOS | Windows | +|---|---|---| +| Data folder | `~/Library/Application Support/OpenMyo` | `%LOCALAPPDATA%\OpenMyo` | +| Cache folder | `~/Library/Caches/OpenMyo` | `%LOCALAPPDATA%\OpenMyo\Cache` | + +## What's in each + +| Folder | Item | Contents | +|---|---|---| +| Data | `settings.json` | Your settings. Never secrets. | +| Data | `secrets/*.bin` | Windows only: your secrets, encrypted with DPAPI for your Windows user. | +| Data | `yoto-refresh.lock` | A lock that keeps the app and the Claude Desktop server from refreshing your Yoto sign-in at the same time. | +| Cache | `cards/` | Cached playlist (card) JSON. | +| Cache | `images/` | Downloaded artwork and icon images. | +| Cache | `icons/public.json` | Yoto's public icon catalog. | +| Cache | `yotoicons/catalog.json` | Local copy of the yotoicons.com catalog, updated automatically. | + +> [!TIP] +> The cache folder is safe to delete. OpenMyo downloads what it needs again. + +## Secrets + +Secrets (your Yoto sign-in tokens and Anthropic API key) aren't kept in settings files. On macOS they're in the Keychain. On Windows they're encrypted with DPAPI and stored in the data folder's `secrets` folder; only your Windows user can decrypt them. + +## Related content + +- [OpenMyo overview](../overview.md) +- [Use OpenMyo with Claude Desktop](../use-with-claude-desktop.md) +- [Cross-cutting concerns: caching](../../contribute/architecture/cross-cutting-concerns.md#caching) diff --git a/docs/user/use-with-claude-desktop.md b/docs/user/use-with-claude-desktop.md new file mode 100644 index 0000000..ccc6449 --- /dev/null +++ b/docs/user/use-with-claude-desktop.md @@ -0,0 +1,43 @@ +--- +title: Use OpenMyo with Claude Desktop +description: Connect OpenMyo to Claude Desktop so Claude can rename playlists and tracks, pick icons, find tracks and play them. +ms.topic: how-to +ms.date: 11/16/2026 +--- + +# Use OpenMyo with Claude Desktop + +OpenMyo can act as an [MCP](https://modelcontextprotocol.io) server, so Claude Desktop can rename playlists and tracks, pick icons, find tracks across your playlists and play them on a Yoto player ("play the Gruffalo on the bedroom Yoto"). It uses your own Claude subscription. You don't need an API key. + +## Prerequisites + +- Claude Desktop. +- OpenMyo, signed in to Yoto. The server uses the Yoto session you already signed in with, so sign in first. + +## Connect + +1. In OpenMyo, open **Settings**. +2. Choose **Connect to Claude Desktop**. This adds OpenMyo to Claude Desktop's configuration. +3. Restart Claude Desktop. + +Claude Desktop starts OpenMyo in the background when it needs it; you don't have to keep the app open. Claude can list and read your playlists, rename playlists and tracks, search and set icons, find tracks, and play them on your Yoto players. + +> [!TIP] +> If you move the app, choose **Connect to Claude Desktop** again. To remove the connection, choose **Disconnect**. + +## Try some prompts + +- "Pick icons for my Odyssey playlist." +- "Which tracks in Bedtime Stories have no icon? Find good ones for them." +- "Number the icons on my Counting Songs playlist." +- "Remove the 'Chapter N -' prefix from every track in The Hobbit." +- "Rename my Bedtime playlist to Bedtime Stories." + +## Undo a change + +Changes save straight to Yoto. Claude Desktop asks before each tool call, and each change reports the previous titles or icons, so you can ask Claude to undo it. + +## Related content + +- [Build the app](build-the-app.md) +- [Claude Desktop connector](../contribute/concepts/claude-desktop-connector.md) diff --git a/src/OpenMyo.App/README.md b/src/OpenMyo.App/README.md index 71fdf29..39cbc1a 100644 --- a/src/OpenMyo.App/README.md +++ b/src/OpenMyo.App/README.md @@ -1,105 +1,20 @@ --- -description: Guide to the OpenMyo.App project; read when adding or changing a screen, panel, view model or style. +description: Pointer to the OpenMyo.App documentation; read when adding or changing a screen, panel, view model or style. --- # OpenMyo.App The Avalonia desktop UI and the composition root. Screens follow MVVM: a view model holds state and commands, a view (`.axaml`) binds to it with compiled bindings, and nothing in a view calls services. +The same executable also runs the Claude Desktop connector when started with `--mcp`. -## File map +The full guide to this project is in the docs: -| Path | Owns | -|---|---| -| [`Program.cs`](Program.cs) | Entry point; chooses window mode or connector mode (`--mcp`) | -| `App.axaml(.cs)` | Loads styles, builds services, opens [`MainWindow`](Screens/Shell/MainWindow.axaml) | -| [`Composition/ServiceRegistration.cs`](Composition/ServiceRegistration.cs) | Every service and view model registration | -| [`Composition/ScreenLinks.cs`](Composition/ScreenLinks.cs) | Every link between pages (sign-in, import → library, library → icon index) | -| [`Composition/McpMode.cs`](Composition/McpMode.cs) | Connector mode: no window | -| [`Screens/Shell/MainViewModel.cs`](Screens/Shell/MainViewModel.cs) | The shell: navigation rail items, navigation, sign-in state | -| [`Screens/Shell/SidebarItem.cs`](Screens/Shell/SidebarItem.cs) | Rail entries and the `SidebarDestination` enum | -| [`Screens/OperationViewModel.cs`](Screens/OperationViewModel.cs) | Base class for screens that run long work | -| `Screens//` | One folder per feature: its views (`.axaml` + `.axaml.cs`) beside their view models, plus row/tile view models and helpers | -| [`Screens/Editor/Commands/`](Screens/Editor/Commands) | The editor's command groups and the interface they use to reach it | -| [`Screens/Shell/MainWindow.axaml`](Screens/Shell/MainWindow.axaml) | Rail layout and the `DataTemplate` that maps each page view model to its view | -| [`Styles/Theme.axaml`](Styles/Theme.axaml) | Colours, brushes, corner radii and rail icon glyphs (`StreamGeometry`) | -| [`Styles/Controls.axaml`](Styles/Controls.axaml) | Control styles and classes such as `card`, `accent`, `largeTitle` | -| [`Services/`](Services) | UI-side services: file pickers, image cache, window access | -| [`Controls/`](Controls), [`Converters/`](Converters) | Reusable controls and binding converters | +- [Start-up and composition](../../docs/contribute/concepts/app-startup.md), + [navigation and commands](../../docs/contribute/concepts/navigation-and-commands.md) and + [library and editor](../../docs/contribute/concepts/library-and-editor.md). +- How-to guides: [add a page to the navigation rail](../../docs/contribute/how-to/add-navigation-page.md), + [add a panel to a screen](../../docs/contribute/how-to/add-panel.md), + [add a setting or a secret](../../docs/contribute/how-to/add-setting-or-secret.md). -## How a page is wired - -```text -SidebarItem (MainViewModel.TopItems / BottomItems) - → MainViewModel.SelectedItem - → MainViewModel.Navigate sets CurrentPage to the page view model - → MainWindow's ContentControl shows CurrentPage - → MainWindow.DataTemplates picks the view for that view model type - → the view binds to the view model (x:DataType) -``` - -A panel inside a page is a child view model exposed as a property of the page view model (for example -[`PlaylistEditorViewModel.Cleanup`](Screens/Editor/PlaylistEditorViewModel.cs)), shown by embedding its view in the page view with -`DataContext="{Binding Cleanup}"`. - -## Which view shows which view model - -```text -Feature View View model Bound via -Shell MainWindow MainViewModel -Library LibraryView LibraryViewModel CurrentPage - BulkActionsView BulkActionsViewModel .Bulk -Editor PlaylistEditorView PlaylistEditorViewModel .Editor - TitleCleanupView TitleCleanupViewModel .Cleanup -Import ImportView ImportViewModel CurrentPage - DraftCardView DraftCardViewModel each draft -IconPicker IconPickerView IconPickerViewModel .Picker (one per owner) - CommunityResultsView CommunityResultsViewModel .Community -Player PlayerBarView PlayerBarViewModel MainViewModel.PlayerBar (docked under every page) - NowPlayingView NowPlayingViewModel .Local (plays on this computer) - RemotePlaybackView RemotePlaybackViewModel .Remote (plays on a Yoto player) - OutputPickerView OutputPickerViewModel .Output (where playback goes) -Settings SettingsView SettingsViewModel CurrentPage - ClaudeDesktopView ClaudeDesktopViewModel .ClaudeDesktop - AiKeyView AiKeyViewModel .AiKey (one copy, also in the picker) -``` - -Rows and tiles in a list (`PlaylistRowViewModel`, `ChapterRowViewModel`, `DraftTrackViewModel`, the icon -tiles, `SidebarItem`) are small `DataTemplate`s inside the list's view, so their view models sit in that -feature folder. A row that grows past a few lines of markup gets its own view. - -## How view models talk to each other - -- **Parent → child:** a parent owns its children (constructor or property) and calls them directly. -- **Child → parent:** a child raises an event about itself (`IconChosen`, `RowsDeleted`); it never holds its - parent. Where a child needs the parent's services, it gets a small interface (`IChapterEditor`, - `IReorderableOwner`), not the parent type. -- **Page → page:** never directly. [`Composition/ScreenLinks.cs`](Composition/ScreenLinks.cs) subscribes to - page events and calls the other page, so every cross-page link is in one file. - -## Local rules - -The full UI rules are CODESTANDARDS §8. The ones that most often catch new screens: - -- View models do not reference Avalonia controls. Code-behind is for view-only concerns and stays under - 60 lines. -- Every view and `DataTemplate` sets `x:DataType`. -- Long work goes through [`OperationViewModel.RunAsync`](Screens/OperationViewModel.cs), with inline progress and a Cancel button. -- Colours come from tokens in [`Styles/Theme.axaml`](Styles/Theme.axaml), never inline hex. -- Every command is reachable by keyboard; icon-only buttons have `ToolTip.Tip` and - `AutomationProperties.Name`. -- A view model is named after its view and sits beside it: `FooView.axaml` ↔ `FooViewModel.cs`. -- When a feature folder passes about 12 files, move one group into a subfolder named for what it holds - (as `Editor/Commands/` does). -- Never start work with `_ = SomethingAsync()`; use `SomethingAsync().Forget(logger, "what it is")` - ([`BackgroundWork`](Services/BackgroundWork.cs)) so a failure is logged instead of lost. The one exception is - [`IconBitmapLoader`](Services/IconBitmapLoader.cs), which never throws. -- Logic worth testing goes in `OpenMyo.Core`; this project has no test project. -- [`MainViewModel`](Screens/Shell/MainViewModel.cs) has 5 constructor dependencies and the hard limit is 8 (CODESTANDARDS §2). - -## Common changes - -- [How to add a page to the navigation rail](../../docs/how-to.md#how-to-add-a-page-to-the-navigation-rail) -- [How to add a panel to an existing screen](../../docs/how-to.md#how-to-add-a-panel-to-an-existing-screen) -- [How to add a setting or a secret](../../docs/how-to.md#how-to-add-a-setting-or-a-secret) -- Background: [The desktop app and the Claude Desktop connector](../../docs/design/app.md) +The UI rules every screen is reviewed against are in [CODESTANDARDS.md §8](../../CODESTANDARDS.md). From c8948dff0c56d7f848492b3b35c0d85647c4a6ac Mon Sep 17 00:00:00 2001 From: djdev0010 <41651107+djdev0010@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:15:01 -0500 Subject: [PATCH 2/2] diagrams --- docs/contribute/architecture/overview.md | 4 +++ docs/contribute/concepts/app-startup.md | 13 +++++++++ .../concepts/claude-desktop-connector.md | 2 ++ docs/contribute/concepts/icon-matching.md | 16 +++++++++++ docs/contribute/concepts/import-pipeline.md | 15 ++++++++++ .../contribute/concepts/library-and-editor.md | 12 ++++++++ docs/contribute/concepts/media-uploads.md | 13 +++++++++ .../concepts/navigation-and-commands.md | 13 +++++++++ .../concepts/read-and-save-cards.md | 12 ++++++++ .../contribute/concepts/sign-in-and-tokens.md | 28 +++++++++++++++++++ .../contribute/concepts/yoto-http-pipeline.md | 27 ++++++++++++++++++ .../concepts/yoto-player-control.md | 18 ++++++++++++ docs/user/import-folders.md | 16 +++++++++++ 13 files changed, 189 insertions(+) diff --git a/docs/contribute/architecture/overview.md b/docs/contribute/architecture/overview.md index e74328d..d93c61a 100644 --- a/docs/contribute/architecture/overview.md +++ b/docs/contribute/architecture/overview.md @@ -31,6 +31,8 @@ the Model Context Protocol (MCP). title: System context diagram for OpenMyo --- flowchart TB + accTitle: System context diagram for OpenMyo + accDescr: A card maker uses OpenMyo directly or through Claude Desktop. OpenMyo talks to the Yoto platform, and optionally to yotoicons.com and the Anthropic API. user["Card maker
[Person]
A parent or teacher who makes
Yoto MYO cards"]:::person claudeDesktop["Claude Desktop
[Software system, external, optional]
Chat app that can call
OpenMyo's tools"]:::ext openmyo["OpenMyo
[Software system]
Bulk-creates and tidies
MYO playlists"]:::system @@ -64,6 +66,8 @@ flowchart TB title: Container diagram for OpenMyo --- flowchart LR + accTitle: Container diagram for OpenMyo + accDescr: The desktop app and the windowless Claude Desktop connector are one executable. Both share the OS secret store, the data and cache folders, and call Yoto, yotoicons.com and, from the app only, Anthropic. user["Card maker
[Person]"]:::person claudeDesktop["Claude Desktop
[Software system, external]"]:::ext diff --git a/docs/contribute/concepts/app-startup.md b/docs/contribute/concepts/app-startup.md index 00dcef4..e6623a2 100644 --- a/docs/contribute/concepts/app-startup.md +++ b/docs/contribute/concepts/app-startup.md @@ -19,6 +19,19 @@ Both build the same services, so a feature in Core is available to the screens a MCP over stdio. Avalonia never starts, and nothing else may write to stdout. See [Claude Desktop connector](claude-desktop-connector.md). +```mermaid +flowchart TD + accTitle: Launch modes + accDescr: The same executable either starts the window, restoring the session and opening the library or Settings, or with --mcp builds the same services and serves tools over stdio without a window. + main["Program.Main"] -->|no arguments| win["Build services,
show main window"] + main -->|--mcp| conn["Build the same services,
no window"] + win --> restore{"Stored session
still works?"} + restore -->|yes| lib["Open the library"] + restore -->|no| settings["Open Settings to sign in"] + conn --> silent["Restore session silently
(never opens a browser)"] + silent --> stdio["Serve tools over stdio"] +``` + ## Composition root [`ServiceRegistration.Build`](../../../src/OpenMyo.App/Composition/ServiceRegistration.cs) is the composition diff --git a/docs/contribute/concepts/claude-desktop-connector.md b/docs/contribute/concepts/claude-desktop-connector.md index 41697d3..2e6ef24 100644 --- a/docs/contribute/concepts/claude-desktop-connector.md +++ b/docs/contribute/concepts/claude-desktop-connector.md @@ -13,6 +13,8 @@ See [App start-up and composition](app-startup.md) for how connector mode boots. ```mermaid sequenceDiagram + accTitle: A Claude Desktop tool call + accDescr: Claude Desktop starts OpenMyo with --mcp and calls a tool over stdio. The tool validates its input, loads the playlist, saves once and returns the previous values so Claude can undo. participant D as Claude Desktop participant M as Connector (stdio) participant T as Tool class (from DI) diff --git a/docs/contribute/concepts/icon-matching.md b/docs/contribute/concepts/icon-matching.md index 0f7ee39..d0c0fb0 100644 --- a/docs/contribute/concepts/icon-matching.md +++ b/docs/contribute/concepts/icon-matching.md @@ -89,6 +89,22 @@ with no matches at all falls back to matches for the playlist title. scores better than Yoto's best. 6. Sets the winner on each chapter and its tracks. Nothing is saved; the caller saves. +```mermaid +flowchart TD + accTitle: Auto-matching icons for a playlist + accDescr: Chapters that already have an icon are skipped unless replacing. Series words are removed, each title is reduced to its subject and searched. A community icon wins only when it scores better than the best Yoto icon. + titles["Chapter titles"] --> skip{"Already has an icon
and not replacing?"} + skip -->|yes| keep["Leave as is"] + skip -->|no| series["Drop series words"] + series --> subject["Reduce to the subject"] + subject --> search["Search the icon index"] + search --> better{"Community icon
scores better?"} + better -->|yes| comm["Use community icon"] + better -->|no| yoto["Use best Yoto or library icon"] + comm --> set["Set on chapter and tracks
(caller saves)"] + yoto --> set +``` + ### Number icons Track *n* can get an icon showing *n*. Yoto's own number icon is used when it exists; otherwise a 16×16 PNG diff --git a/docs/contribute/concepts/import-pipeline.md b/docs/contribute/concepts/import-pipeline.md index 820c53f..ff00d1d 100644 --- a/docs/contribute/concepts/import-pipeline.md +++ b/docs/contribute/concepts/import-pipeline.md @@ -14,6 +14,21 @@ network access. Then the screen asks for icon suggestions, the user reviews, and playlist. Podcast feeds skip `DraftBuilder` but join the same screen and publishing path. See [Podcast feed import](podcast-feed-import.md). +```mermaid +flowchart LR + accTitle: From dropped files to a created playlist + accDescr: Dropped files are grouped, ordered, titled and given artwork offline to make drafts. Podcast feeds make drafts too. The user reviews drafts with icon suggestions, then publishing uploads media and creates the card. + files["Dropped folders
and files"] --> group["Group into
playlists"] --> order["Order
tracks"] --> titles["Clean
titles"] --> art["Find
artwork"] --> drafts["Drafts"] + feed["Podcast feed"] -.-> drafts + drafts --> review["Icon suggestions
and user review"] --> publish["Upload audio, icons, cover"] --> card["Create card
(one save)"] + subgraph offline["Offline, no network"] + group + order + titles + art + end +``` + ## Which files become which playlist - Dropped folders are expanded recursively to audio files; hidden files are skipped. diff --git a/docs/contribute/concepts/library-and-editor.md b/docs/contribute/concepts/library-and-editor.md index bb5ccee..a1a86c7 100644 --- a/docs/contribute/concepts/library-and-editor.md +++ b/docs/contribute/concepts/library-and-editor.md @@ -35,6 +35,18 @@ drag-reorder, icon, delete) sets `IsDirty`. - **Revert** shows `_original` again. - **Add tracks** and **Change cover** upload first and then save immediately. +```mermaid +stateDiagram-v2 + accTitle: Editor states + accDescr: A loaded playlist becomes dirty after any edit. Save writes it to Yoto and shows the saved result; Revert goes back to the loaded playlist. + [*] --> Clean: Playlist opened + Clean --> Dirty: Rename, reorder, icon, delete + Dirty --> Dirty: More edits + Dirty --> Clean: Save (patches the card) + Dirty --> Clean: Revert (back to original) + Clean --> Clean: Add tracks / change cover (saves at once) +``` + The editor's command groups live beside it in `Screens/Editor/`. They reach the editor only through `IChapterEditor` (run work, read the current playlist, apply changed chapters), which keeps the editor file small. diff --git a/docs/contribute/concepts/media-uploads.md b/docs/contribute/concepts/media-uploads.md index d986235..2e0bb2f 100644 --- a/docs/contribute/concepts/media-uploads.md +++ b/docs/contribute/concepts/media-uploads.md @@ -22,6 +22,19 @@ to Yoto. 4. Poll `media/upload/{id}/transcoded` (404 means "not yet") with backoff until a timeout. 5. Return `yoto:#` with the format, duration, size and channels Yoto reports. +```mermaid +flowchart TD + accTitle: Uploading an audio file + accDescr: The file is hashed and Yoto is asked for an upload URL. Only new bytes are uploaded. The uploader then polls until Yoto finishes transcoding, and returns the media reference. + hash["Hash the file"] --> ask["Ask Yoto for an upload URL"] + ask --> seen{"Yoto already has
these bytes?"} + seen -->|no| put["PUT the file to storage"] + seen -->|yes| poll + put --> poll{"Transcoded yet?"} + poll -->|not yet| wait["Wait, back off"] --> poll + poll -->|done| ref["Return yoto:# reference
and media details"] +``` + ## Cover `POST media/coverImage/user/me/upload` returns a public URL that goes in `metadata.cover.imageL`. diff --git a/docs/contribute/concepts/navigation-and-commands.md b/docs/contribute/concepts/navigation-and-commands.md index 3b7621a..1d5f77e 100644 --- a/docs/contribute/concepts/navigation-and-commands.md +++ b/docs/contribute/concepts/navigation-and-commands.md @@ -31,6 +31,19 @@ see [Add a page to the navigation rail](../how-to/add-navigation-page.md) and [`ScreenLinks`](../../../src/OpenMyo.App/Composition/ScreenLinks.cs) subscribes to page events and calls the other page, so every cross-page link is in one file. +```mermaid +flowchart LR + accTitle: How view models talk to each other + accDescr: A page owns its child panels and calls them directly. Children raise events back to their parent. Pages never reference each other; ScreenLinks listens to page events and calls the other page. + subgraph pageA["Page view model"] + child["Child panel"] + end + pageA -->|owns, calls| child + child -.->|raises events| pageA + pageA -.->|events| links["ScreenLinks"] + links -->|calls| pageB["Other page view model"] +``` + ## Commands Every button and menu item runs a command on a view model: the view binds `Command="{Binding …}"`, and the diff --git a/docs/contribute/concepts/read-and-save-cards.md b/docs/contribute/concepts/read-and-save-cards.md index 5829b6f..6632069 100644 --- a/docs/contribute/concepts/read-and-save-cards.md +++ b/docs/contribute/concepts/read-and-save-cards.md @@ -30,6 +30,18 @@ Because saving replaces the whole card, rebuilding JSON from the domain model wo OpenMyo does not model (and Yoto adds fields over time). So a save *patches* the last-fetched document instead. [`CardComposer`](../../../src/OpenMyo.Yoto/Content/CardComposer.cs) is the entry point: +```mermaid +flowchart LR + accTitle: Saving a card by patching the last-fetched document + accDescr: The last-fetched raw card and the edited playlist are combined. Raw chapters are matched by key and cloned, then renumbered, and the whole card is posted back to Yoto. + raw["Last-fetched raw card
(cache or GET)"] --> clone["Deep clone,
drop server-managed fields"] + edit["Edited playlist
(order, titles, icons)"] --> match + clone --> match["Match each chapter
to its raw node by key"] + match --> renum["Renumber keys,
set labels and icons"] + renum --> post["POST content
(replaces the whole card)"] +``` + + 1. `SaveAsync` takes the cached raw card (or fetches it) as the base. 2. The composer deep-clones it, removes server-managed fields (`createdAt`, `updatedAt`, `_id`, `userId`), checks title lengths, and sets the title, cover URL and totals. diff --git a/docs/contribute/concepts/sign-in-and-tokens.md b/docs/contribute/concepts/sign-in-and-tokens.md index 720e6c2..4180a3c 100644 --- a/docs/contribute/concepts/sign-in-and-tokens.md +++ b/docs/contribute/concepts/sign-in-and-tokens.md @@ -14,6 +14,8 @@ client secret. Sign-in is Authorization Code + PKCE with a loopback redirect: ```mermaid sequenceDiagram + accTitle: Signing in with PKCE and a loopback redirect + accDescr: The app starts a local listener and opens Yoto's sign-in page in the browser. Yoto redirects back to the listener with a code, which the app exchanges for tokens and stores the refresh token. participant A as App participant L as Loopback listener participant B as System browser @@ -52,6 +54,32 @@ redirect URI is fixed, because the user must register it with their OAuth client The refresh token is read *inside* both locks, because the other process may have just replaced it. - `RefreshAccessTokenAsync(rejectedToken)` only refreshes if the current token is still the rejected one. So ten requests that all get a 401 cause one refresh, not ten. + +The diagram shows why the refresh token is read inside the lock: when the app and the connector both +need a new token, the second one finds the token already replaced and uses the new one. + +```mermaid +sequenceDiagram + accTitle: Refreshing a single-use token from two processes + accDescr: The app takes the file lock, reads the refresh token, refreshes and stores the new token. The connector waits for the lock, then reads the new token, so the old one is never used twice. + participant App + participant Lock as Refresh lock file + participant Store as Secret store + participant Yoto as Yoto login + participant Conn as Connector + + App->>Lock: Acquire + Conn->>Lock: Acquire (waits) + App->>Store: Read refresh token R1 + App->>Yoto: Refresh with R1 + Yoto-->>App: Access token + refresh token R2 + App->>Store: Store R2 + App->>Lock: Release + Lock-->>Conn: Acquired + Conn->>Store: Read refresh token R2 + Conn->>Yoto: Refresh with R2 + Note over App,Conn: Reading R1 outside the lock would send it twice and sign the user out +``` - A 400/401/403 from the token endpoint clears the session (the user must sign in again). - `TryRestoreAsync` also compares the stored scope with the current scope list. If the app now asks for more scopes, the old token is dropped, because refreshing cannot widen a grant. diff --git a/docs/contribute/concepts/yoto-http-pipeline.md b/docs/contribute/concepts/yoto-http-pipeline.md index 40480e5..e234a55 100644 --- a/docs/contribute/concepts/yoto-http-pipeline.md +++ b/docs/contribute/concepts/yoto-http-pipeline.md @@ -23,6 +23,33 @@ A request on `yoto-api` goes through the handlers in order: 2. The auth handler adds `Authorization: Bearer …`. On a **401** it asks the session for a new token once and resends once. +```mermaid +sequenceDiagram + accTitle: A request through the Yoto API client + accDescr: The retry handler passes the request to the auth handler, which adds the bearer token. A 401 triggers one token refresh and one resend. A 429 or 503 makes the retry handler wait and try again. + participant Caller + participant Retry as Retry handler + participant Auth as Auth handler + participant Session as Yoto session + participant API as Yoto API + + Caller->>Retry: Request + Retry->>Auth: Attempt + Auth->>Session: Access token + Auth->>API: Request + bearer token + alt 401 + API-->>Auth: 401 + Auth->>Session: Refresh (once) + Auth->>API: Resend once + end + alt 429 or 503 + API-->>Retry: 429 / 503 + Retry->>Retry: Wait (Retry-After) + Retry->>Auth: Next attempt + end + API-->>Caller: Response, or YotoApiException +``` + Both only resend when the body can be sent again. The upload client deliberately has no auth handler, so the bearer token never reaches the storage host. Non-success responses become `YotoApiException`. diff --git a/docs/contribute/concepts/yoto-player-control.md b/docs/contribute/concepts/yoto-player-control.md index 6540110..19d7f42 100644 --- a/docs/contribute/concepts/yoto-player-control.md +++ b/docs/contribute/concepts/yoto-player-control.md @@ -51,6 +51,24 @@ neighbouring chapter or a new `secondsIn`. `YotoPlayerRemote` holds one shared connection per player; the bar, the live list and commands all use it: +```mermaid +stateDiagram-v2 + accTitle: Lifecycle of one player connection + accDescr: After sign-in each online player is connected and watched. Keep-alives stop Yoto closing a quiet connection. An unexpected drop is retried once; if that fails the player is reported gone. Sign-out closes the connection. + [*] --> Watching: Sign-in, player online + Watching --> Watching: Keep-alive / state events + Watching --> Controlling: Chosen as output + Controlling --> Watching: Output switched away + Watching --> Retrying: Unexpected drop + Controlling --> Retrying: Unexpected drop + Retrying --> Watching: Reconnected with fresh token + Retrying --> Gone: Second failure + Gone --> [*] + Watching --> [*]: Sign-out + Controlling --> [*]: Sign-out +``` + + - From sign-in the app connects to every online player so it can show ones already playing. Watching only listens. Signing out closes every connection. - Switching the output away from a player does not disconnect it; the live list keeps watching it. diff --git a/docs/user/import-folders.md b/docs/user/import-folders.md index 34c1d9d..73e8abb 100644 --- a/docs/user/import-folders.md +++ b/docs/user/import-folders.md @@ -26,6 +26,22 @@ Use bulk import to turn folders or audio files into Yoto playlists. Each folder **Order.** Tracks are ordered by disc and track tags, then leading numbers, then name. +**Folders.** Every folder that holds audio becomes one playlist. Disc folders such as `CD1` and `CD2` join the folder above them, so a two-CD audiobook becomes one playlist: + +```mermaid +flowchart LR + accTitle: How folders become playlists + accDescr: An audiobook folder with CD1 and CD2 subfolders becomes one playlist. A separate songs folder becomes a second playlist. + subgraph disk["Folders you drop"] + book["Gruffalo audiobook/"] --- cd1["CD1/"] + book --- cd2["CD2/"] + songs["Bedtime songs/"] + end + cd1 --> p1["Playlist: Gruffalo audiobook"] + cd2 --> p1 + songs --> p2["Playlist: Bedtime songs"] +``` + **Cover art.** The cover comes from an image in the folder (`cover.jpg`, `folder.jpg`, and so on) or from art embedded in the audio. **Track icons.** A track gets an icon from an image with the same base name as its audio file. To match icons from titles instead, see [Match icons to tracks](match-icons.md).