Home

Welcome to SwanSong

The WonderSwan is small, strange, clever, and still full of surprises. SwanSong gives it the Mac app it always deserved: a beautiful private library, a focused native player, and an unusually deep workshop for people who translate, make, write, test, and preserve WonderSwan software.

You do not need to study the wiki before playing. Open a game and go. Come back when you want to tune a controller, move a save, translate a screen, build a game, work with a real cartridge, or understand exactly how SwanSong protects your private material.

SwanSong requires macOS 14 or later and supports Apple silicon and Intel Macs. No games or original system firmware are included.

Pick your path

I want to play

Start with Playing and Library. It covers adding games, artwork, favorites, the native player, display choices, Time Ribbon, visual save states, Game Confidence, and Pocket save exchange. Gamepads explains presets, custom mapping, hotplug, battery status, and the limits of macOS controller support.

There is no BIOS setup. Open IPL explains the independent startup system included with SwanSong 0.2 and later.

I want to translate a game

Translation Lab is the complete guide to deterministic routes, Original and Patched frame pairs, First Visual Change, on-device text intake, observed play, private display provenance, and durable evidence review.

If a trusted local agent will help with a long route or evidence task, read Local MCP and Automation before enabling anything.

I want to write or publish a novel

Story Forge brings the schema-v3 light-novel framework into a native workspace for concept, outline, draft, revision, ImageGen illustration review, catalog originality, optional music, and EPUB/PDF publication. It keeps automated checks separate from human editorial and release approval.

Story Forge is a current-source preview and is not included in the public 0.4.3 download yet.

I want to make a game

SwanSong Studio puts New, Assets, Build, Test, Play, Profile, Evidence, and Release in one native workspace backed by SwanSong SDK. SwanSong 0.4.3 carries a content-verified SDK 0.4.0 payload, typed visual-authoring tools, replay timelines, and deterministic failing-plan minimization. Python 3.11+ and the pinned Wonderful packages remain honest local prerequisites checked by Doctor.

I want homebrew or real hardware

Homebrew Catalog explains the signed first-party catalog included in the public 0.4.3 beta. It never loads at launch or merely because you opened Homebrew; Browse, Refresh, and Add to Library are choices you make.

Analogue Pocket SD Setup explains how SwanSong can merge an authorized Core release onto a selected card without formatting it or touching games, saves, Memories, settings, Presets, or unrelated cores. The workflow remains locked until the separate SwanSong Core project publishes a verified stable release.

Cartridge Lab shows how current source can use a WonderSwan Color or SwanCrystal, Yokoi Boot, and a 3.3 V ExtFriend-compatible adapter to make verified cartridge and save backups or restore an exact-size save with physical confirmation. Cartridge Lab is not part of the public 0.4.3 download yet.

I want to contribute or release SwanSong

Start with Architecture and Source Ownership, then use Build and Test as the command reference. Signing and Notarization and Release Gates document the trusted-Mac path from a clean source tag to a signed, notarized, checksummed public build.

Public beta and what comes next

The current public 0.4.3 beta adds the verified SDK 0.4.0, exact-frame keypad delivery, published Homebrew Catalog, typed visual-authoring tools, replay timelines, failing-plan minimization, bounded USB Hardware Lab, broader native design pass, clearer updater dashboard, and game/window fitting built around the native 224×157 display. Its GitHub download is Developer ID signed, notarized, stapled, checksummed, and available through the opt-in beta update channel.

Use 0.4 Beta Testing for the current tester checklist and the repository changelog for the exact source status.

Current source is already building the next chapter: Story Forge carries a novel from idea to EPUB/PDF and into Studio for adaptation, while Cartridge Lab puts a real WonderSwan back into the preservation loop. These previews are documented now so contributors can test them honestly, but they are not being advertised as features of the signed 0.4.3 download.

Private by default, explicit when online

SwanSong has no accounts, ads, analytics, telemetry, crash-reporting service, or system profiling. Your games, saves, states, screenshots, controller setup, translation evidence, Studio projects, preview manuscripts, and hardware backups stay on the Mac.

Three separate features can contact GitHub, and only under their own rules:

• the app updater checks when you ask or after you enable automatic checks;
• the Homebrew Catalog loads, refreshes, or downloads a selected title when you choose that action; and
• the Analogue Pocket page checks for a Core release only when you ask.

Read App Updates, the privacy policy, and the relevant feature page for the exact data and trust boundary.

A note about historical releases

Versioned notes remain authoritative for old behavior. SwanSong 0.1.0 used user-supplied startup files. Version 0.1.1 made Open IPL the normal path while retaining a private compatibility override. Version 0.2 removed original firmware import, storage, and override completely. Current policy should not be retroactively described as behavior that existed in 0.1.x.