164 lines
6.4 KiB
Markdown
164 lines
6.4 KiB
Markdown
<div align="center">
|
||
|
||
<h1>OmniMTP</h1>
|
||
|
||
<p>Ein schneller (<strong>3–4× schneller als direkter microSD-Zugriff</strong>), nativer macOS-MTP-Client für die Nintendo Switch.<br>
|
||
Übertrage NSP-, XCI- und NRO-Dateien per USB-C, ohne die microSD-Karte auszubauen.</p>
|
||
|
||
[](https://www.apple.com/macos/)
|
||
[](LICENSE)
|
||
[]()
|
||
[]()
|
||
|
||
<br>
|
||
|
||
<img src="OmniMTP.png" width="820" alt="OmniMTP Screenshot" />
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
> **Herkunft:** OmniMTP ist eine Weiterentwicklung von [heziMTP](https://github.com/helzeiah/heziMTP), dem ursprünglichen Projekt-Repository.
|
||
|
||
## Funktionen
|
||
|
||
- **Direkter USB-C-Transfer** — kommuniziert mit DBI oder Sphaira im MTP-Modus über USB, ohne SD-Kartenwechsel
|
||
- **Schnell** — USB-3.0-Unterstützung mit adaptiver Chunk-Größe; realistisch 60–150+ MB/s, abhängig von Switch und Kabel
|
||
- **Zwei-Panel-Dateibrowser** — Mac-Dateisystem links, Switch rechts; Dateien per Drag & Drop zwischen beiden Seiten verschieben
|
||
- **Mehrfachübertragung** — mehrere Dateien mit Cmd+Klick oder Shift+Klick auswählen und gemeinsam ziehen
|
||
- **Große Dateien** — Dateien >4 GB werden korrekt unterstützt
|
||
- **Automatische Geräteerkennung** — einstecken und loslegen, kein manuelles Scannen nötig
|
||
- **Modernes macOS-UI** — natives Dark Mode, SF Pro, macOS-12+-Fensterdesign
|
||
- **Keine Abhängigkeiten** — libusb ist statisch eingebunden; nichts extra installieren
|
||
|
||
## Voraussetzungen
|
||
|
||
- **Mac:** macOS 12 Monterey oder neuer (Universal Binary — Apple Silicon + Intel)
|
||
- **Switch:** Custom Firmware mit [DBI](https://github.com/rashevskyv/dbi) oder [Sphaira](https://github.com/ITotalJustice/sphaira)
|
||
- **Kabel:** ein Kabel mit Datenübertragung (kein reines Ladekabel)
|
||
|
||
## Erste Schritte
|
||
|
||
### 1. Switch vorbereiten
|
||
|
||
In DBI: **Tools → MTP Responder**
|
||
|
||
In Sphaira: **Tools → MTP**
|
||
|
||
USB-C-Kabel anschließen und den Bildschirm offen lassen
|
||
|
||
### 2. Aus dem Quellcode bauen
|
||
|
||
```bash
|
||
git clone https://github.com/helzeiah/OmniMTP.git
|
||
cd OmniMTP
|
||
./build.sh # Release-Build
|
||
./build.sh run # bauen + starten
|
||
```
|
||
|
||
Oder manuell:
|
||
|
||
```bash
|
||
cmake -B build -DCMAKE_BUILD_TYPE=Release
|
||
cmake --build build -j$(sysctl -n hw.logicalcpu)
|
||
open build/OmniMTP.app
|
||
```
|
||
|
||
**Build-Abhängigkeiten** (werden von CMake automatisch geladen):
|
||
|
||
- libusb 1.0.27
|
||
- keine weiteren externen Abhängigkeiten
|
||
|
||
### 3. Dateien übertragen
|
||
|
||
- **Links** den Mac durchsuchen, **rechts** die Switch
|
||
- **Ziehen:** links → rechts = hochladen, rechts → links = herunterladen
|
||
- **Doppelklick** auf eine lokale Datei lädt sie bei aktiver Verbindung direkt hoch
|
||
- **Rechtsklick** für Kontextmenü (Auf Switch hochladen / Auf Mac laden / Löschen)
|
||
- **Add Files** öffnet einen nativen Datei-Dialog für Mehrfach-Uploads
|
||
|
||
## Wie schnell ist es?
|
||
|
||
| Verbindung | Typische Geschwindigkeit |
|
||
| ---------------------------------------- | ------------------------ |
|
||
| USB 2.0 | 25–45 MB/s |
|
||
| USB 3.0 (Switch OLED / direktes USB-C 3.x) | 60–150+ MB/s |
|
||
|
||
Die Geschwindigkeit hängt von der microSD-Schreibgeschwindigkeit (Uploads) und der USB-Verbindung ab. Eine schnelle UHS-I-Karte plus USB-3.0-Kabel bringt das meiste raus.
|
||
|
||
## Hinweis zur Installation (macOS Gatekeeper)
|
||
|
||
Da OmniMTP nicht mit einem Apple-Developer-Zertifikat notarisiert ist, zeigt macOS beim ersten Start eine Warnung **„Unbekannter Entwickler“**. Das ist bei Open-Source-Apps außerhalb des App Store normal.
|
||
|
||
**So öffnest du die App:**
|
||
|
||
**Option A — Rechtsklick (am einfachsten)**
|
||
Rechtsklick (oder Control-Klick) auf `OmniMTP.app` → **Öffnen** → im Dialog erneut **Öffnen**. Das musst du nur einmal machen.
|
||
|
||
**Option B — Terminal**
|
||
```bash
|
||
xattr -r -d com.apple.quarantine /Applications/OmniMTP.app
|
||
# oder wo auch immer du die App abgelegt hast:
|
||
xattr -r -d com.apple.quarantine ~/Downloads/OmniMTP.app
|
||
```
|
||
|
||
**Option C — Systemeinstellungen**
|
||
Systemeinstellungen → Datenschutz & Sicherheit → Bereich Sicherheit → **Trotzdem öffnen**.
|
||
|
||
---
|
||
|
||
## Fehlerbehebung
|
||
|
||
**Die App erkennt meine Switch nicht**
|
||
|
||
- Prüfe, ob DBI oder Sphaira im MTP-Modus läuft (nicht nur im Home-Menü)
|
||
- Probiere ein anderes USB-C-Kabel — viele Ladekabel haben keine Datenleitungen
|
||
- Klicke in der App auf **Scan**
|
||
|
||
**Fehler „Operation not supported“**
|
||
|
||
- DBI/Sphaira auf eine aktuelle Version aktualisieren
|
||
- Sphaira: sicherstellen, dass du im Menü **MTP Install** bist
|
||
|
||
## Geplante Erweiterungen
|
||
|
||
- **Breitere MTP-Geräteunterstützung** — die MTP/USB-Schicht ist geräteunabhängig. Android-Handys, Kameras und andere MTP-Geräte sollten mit kleinen Anpassungen an Erkennung und Protokoll funktionieren
|
||
- Ordner-Upload (rekursiv)
|
||
- Unterbrochene Übertragungen fortsetzen
|
||
- Warteschlange umsortieren
|
||
- Dateien auf dem Gerät umbenennen
|
||
|
||
## Bauen
|
||
|
||
```
|
||
./build.sh # Release (Standard)
|
||
./build.sh debug # Debug-Build
|
||
./build.sh run # Release + starten
|
||
./build.sh clean # Build-Verzeichnisse löschen
|
||
```
|
||
|
||
Das Build-System lädt libusb aus dem Quellcode und kompiliert es statisch — kein Homebrew oder Systempakete nötig.
|
||
|
||
## Architektur
|
||
|
||
```
|
||
src/
|
||
├── main.mm Einstiegspunkt (NSApp + WKWebView)
|
||
├── ui/
|
||
│ ├── App.hpp/.mm Backend: Geräteüberwachung, lokale/remote Dateien, Transfers
|
||
│ ├── WebUI.hpp/.mm Bridge: WKWebView-Setup + JS↔C++ Message Handler
|
||
│ └── webroot/ Frontend: HTML/CSS/JS (ohne Build-Schritt, ohne Frameworks)
|
||
├── mtp/
|
||
│ ├── MTPProtocol.hpp MTP-Konstanten, Container-Format, Datenstrukturen
|
||
│ ├── MTPSession.* USB/libusb-Transport, Chunked Transfers
|
||
│ └── MTPOperations.* High-Level-MTP-Operationen (GetObject, SendObject, …)
|
||
└── transfer/
|
||
└── TransferEngine.* Hintergrund-Warteschlange mit Fortschrittsanzeige
|
||
```
|
||
|
||
Die UI ist eine WKWebView-basierte HTML/CSS/JS-App, die über native Message Passing mit einem C++20-MTP-Backend spricht. Kein Electron, kein Node, keine externe Runtime — nur AppKit + WebKit + libusb.
|
||
|
||
## Lizenz
|
||
|
||
MIT — siehe [LICENSE](LICENSE).
|