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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 6 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -36,7 +38,7 @@ eng/check-file-sizes.sh # enforce CODESTANDARDS §2 file limits
| Yoto HTTP calls, JSON mapping, OAuth | `src/OpenMyo.Yoto/<Feature>/` |
| Claude prompt / API call | `src/OpenMyo.Claude/` |
| Keychain/DPAPI, tags, settings, paths | `src/OpenMyo.Infrastructure/<Feature>/` |
| Screens and view models, styles | `src/OpenMyo.App/Screens/<Feature>/` (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/<Feature>/` (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
Expand Down
3 changes: 2 additions & 1 deletion CODESTANDARDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
31 changes: 18 additions & 13 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand Down
71 changes: 28 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
@@ -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 <https://yoto.dev> 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

Expand All @@ -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

Expand Down
Loading
Loading