{"id":50491338,"url":"https://github.com/pzzzy/macwamp","last_synced_at":"2026-06-02T03:04:13.235Z","repository":{"id":361910693,"uuid":"1256404597","full_name":"pzzzy/macwamp","owner":"pzzzy","description":"Native macOS Apple Silicon Winamp-classic recreation in Swift/AppKit","archived":false,"fork":false,"pushed_at":"2026-06-01T20:14:43.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T20:26:53.812Z","etag":null,"topics":["appkit","apple-silicon","avfoundation","macos","music-player","swift","winamp"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pzzzy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T18:43:00.000Z","updated_at":"2026-06-01T20:14:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pzzzy/macwamp","commit_stats":null,"previous_names":["pzzzy/macwamp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pzzzy/macwamp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzzzy%2Fmacwamp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzzzy%2Fmacwamp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzzzy%2Fmacwamp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzzzy%2Fmacwamp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pzzzy","download_url":"https://codeload.github.com/pzzzy/macwamp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzzzy%2Fmacwamp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33803740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appkit","apple-silicon","avfoundation","macos","music-player","swift","winamp"],"created_at":"2026-06-02T03:04:06.894Z","updated_at":"2026-06-02T03:04:13.227Z","avatar_url":"https://github.com/pzzzy.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MacWamp\n\nMacWamp is a native macOS / Apple Silicon experiment that recreates the feel of the classic Winamp interface using AppKit and AVFoundation.\n\nThe project is intentionally small and hackable: it is a Swift Package executable, not a large Xcode workspace. It draws the player, equalizer, and playlist windows manually in a classic pixel-art coordinate system, then uses native macOS audio APIs for local playback.\n\n## Current status\n\nMacWamp is an early public release / proof of concept. It already includes:\n\n- native borderless AppKit windows\n- classic 275 x 116 main player layout at 2x integer pixel scale\n- transport controls, position, volume, balance, shuffle, repeat, eject/open\n- accurate bitrate / sample-rate / mono-stereo metadata via AudioToolbox\n- AVAudioEngine playback\n- a real AVAudioUnitEQ-backed equalizer window\n- playlist window with add/remove/select/clear, drag-and-drop files/folders, recursive folder import, scrolling, and double-click-to-play\n- keyboard shortcuts for common Winamp-style controls\n- optional local skin asset loading for private compatibility work\n\n## Legal / asset notice\n\nThis repository does not redistribute Winamp source code, Winamp bitmap resources, or Winamp trademarks.\n\nDuring development, the original Winamp source release and the Linamp community remake were used as local references for behavior, architecture, and coordinate research. Their code and assets are not vendored here.\n\nThe public repository is source-only and ships with a programmatic fallback skin so it can build and run without proprietary or ambiguously licensed assets. For private/local research, you may provide your own compatible classic skin bitmap sheets under:\n\n```text\nSources/MacWamp/Resources/WinampClassic/\n```\n\nExpected optional filenames:\n\n```text\nmain.bmp\ncbuttons.bmp\ntitlebar.bmp\nnumbers.bmp\ntext.bmp\nvolume.bmp\nbalance.bmp\nposbar.bmp\nplaypaus.bmp\nmonoster.bmp\nshufrep.bmp\npledit.bmp\neqmain.bmp\n```\n\nOnly add assets that you have the right to use and distribute. Do not open a pull request that includes third-party skin files unless their license clearly permits redistribution.\n\n## Requirements\n\n- macOS 14 or newer\n- Apple Silicon or Intel Mac supported by the Swift toolchain\n- Xcode command line tools / Swift 6+\n\nCheck your toolchain:\n\n```sh\nswift --version\n```\n\n## Fully automated local setup with classic assets\n\nFor a local install that imports compatible classic bitmap sheets automatically, run:\n\n```sh\nscripts/setup-assets.sh\n```\n\nFor unattended setup after you have reviewed and accepted the upstream Winamp licensing terms:\n\n```sh\nscripts/setup-assets.sh --accept-winamp-license --yes\n```\n\nTo use an existing local Winamp checkout instead of downloading one:\n\n```sh\nscripts/setup-assets.sh --source /path/to/winamp --accept-winamp-license\n```\n\nThe setup wizard imports only into your local working copy. Imported `.bmp` files are ignored by git and are not redistributed by this repository.\n\n## Build\n\n```sh\nswift build\n```\n\n## Run\n\nLaunch without a file:\n\n```sh\nswift run MacWamp\n```\n\nLaunch with an audio file or a folder of audio files:\n\n```sh\nswift run MacWamp /path/to/song.mp3\nswift run MacWamp /path/to/music-folder\n```\n\nLaunch with the EQ and resizable playlist windows already open:\n\n```sh\nswift run MacWamp /path/to/song.mp3 --show-eq --show-playlist\n```\n\nInside the app:\n\n- click eject/open to choose an audio file\n- drag an audio file or folder onto the main or playlist window\n- drag the playlist lower-right grip to resize it and show more rows\n- double-click a playlist row to play it\n- use the main EQ and PL buttons to show/hide auxiliary windows\n\n## Keyboard shortcuts\n\n| Key | Action |\n| --- | --- |\n| Space | Pause/resume |\n| O | Open file |\n| X | Play |\n| C | Pause/resume |\n| V | Stop |\n| Z | Previous playlist item |\n| B | Next playlist item |\n| S | Shuffle |\n| R | Repeat |\n| E | Toggle equalizer |\n| L | Toggle playlist |\n| Q | Quit |\n\n## Architecture\n\n```text\nPackage.swift\nSources/MacWamp/\n  App.swift            Application delegate, controller, playback, playlist state\n  WinampView.swift     Main player rendering and hit-testing\n  AuxWindows.swift     Equalizer and playlist windows\n  WinampSkin.swift     Sprite-sheet drawing and fallback skin generation\n```\n\nImportant implementation choices:\n\n- AppKit is used directly rather than SwiftUI so the UI can keep the classic pixel coordinate model.\n- Rendering uses flipped views, integer scaling, and nearest-neighbor interpolation.\n- Hit tests are manual rectangles in original-style pixel coordinates.\n- Playback uses AVAudioEngine + AVAudioPlayerNode + AVAudioUnitEQ.\n- Audio metadata comes from AudioToolbox when possible, with file-size fallback for bitrate.\n\n## Quality checks\n\nRun before submitting changes:\n\n```sh\nswift build\nswift package dump-package \u003e/tmp/macwamp-package.json\n```\n\nA GUI smoke test can be done locally with a short sample file:\n\n```sh\nswift run MacWamp /path/to/sample.mp3 --show-eq --show-playlist\n```\n\n## Roadmap\n\n- exact clean-room skin art or explicit support for user-installed skins\n- app bundle packaging and notarization\n- more faithful Winamp EQ curve matching\n- spectrum analyzer driven from FFT rather than metering approximation\n- playlist save/load formats\n- window snapping and shade modes\n- automated UI snapshot tests\n\n## Contributing\n\nContributions are welcome, especially careful macOS/AppKit fidelity fixes. Please keep the legal boundary clean: do not commit third-party Winamp assets, proprietary skin files, or copied code from sources whose license does not allow redistribution.\n\n## License\n\nMacWamp source code in this repository is licensed under GPL-3.0-or-later. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpzzzy%2Fmacwamp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpzzzy%2Fmacwamp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpzzzy%2Fmacwamp/lists"}