{"id":13457363,"url":"https://github.com/mebtte/cicada","last_synced_at":"2026-05-19T06:05:20.092Z","repository":{"id":37473946,"uuid":"376466060","full_name":"mebtte/cicada","owner":"mebtte","description":"A multi-user music service for self-hosting.","archived":false,"fork":false,"pushed_at":"2026-05-11T12:43:12.000Z","size":23164,"stargazers_count":1100,"open_issues_count":4,"forks_count":78,"subscribers_count":7,"default_branch":"v2","last_synced_at":"2026-05-11T14:36:13.770Z","etag":null,"topics":["docker","music","music-player","music-service","pwa","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/mebtte.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2021-06-13T07:05:09.000Z","updated_at":"2026-05-11T05:15:10.000Z","dependencies_parsed_at":"2024-03-07T08:44:40.135Z","dependency_job_id":"595447b3-a1a6-40c0-b94f-9311f090742d","html_url":"https://github.com/mebtte/cicada","commit_stats":{"total_commits":1000,"total_committers":4,"mean_commits":250.0,"dds":0.01200000000000001,"last_synced_commit":"5b98c73ed4e2113182a4445be455ebfd85b8353e"},"previous_names":[],"tags_count":144,"template":false,"template_full_name":null,"purl":"pkg:github/mebtte/cicada","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mebtte%2Fcicada","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mebtte%2Fcicada/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mebtte%2Fcicada/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mebtte%2Fcicada/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mebtte","download_url":"https://codeload.github.com/mebtte/cicada/tar.gz/refs/heads/v2","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mebtte%2Fcicada/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33204089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"online","status_checked_at":"2026-05-19T02:00:06.763Z","response_time":58,"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":["docker","music","music-player","music-service","pwa","self-hosted"],"created_at":"2024-07-31T08:01:41.357Z","updated_at":"2026-05-19T06:05:20.068Z","avatar_url":"https://github.com/mebtte.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Cicada\n\nA multi-user music service for self-hosting.\n\n![version](https://img.shields.io/github/v/release/mebtte/cicada?style=for-the-badge)\n![release build](https://img.shields.io/github/actions/workflow/status/mebtte/cicada/build_and_release.yaml?label=release%20build\u0026style=for-the-badge)\n![docker build](https://img.shields.io/github/actions/workflow/status/mebtte/cicada/docker_build_and_push.yaml?label=docker%20build\u0026style=for-the-badge)\n![license](https://img.shields.io/github/license/mebtte/cicada?style=for-the-badge)\n\n![img](./docs/screenshot.png)\n\n## Feature\n\n- No collection of privacy\n- No advertisements\n- Multiple users\n- Shared musicbill between users\n- Support of importing music and music directory\n- Separation of playlist and custom playqueue\n- Search of music, singer, musicbill and lyric\n- Support of Two-Factor Authentication\n- [PWA](https://developer.mozilla.org/docs/Web/Progressive_web_apps) supports both desktop and mobile\n- Support of building APP from [HTTP API](https://www.postman.com/cicada-player/workspace/cicada-v2)\n\n## Deployment\n\nYou can deploy cicada by under options, and initial user of cicada is `username:cicada/password:cicada`.\n\n### Binary\n\nDownload from [releases](https://github.com/mebtte/cicada/releases) and start server:\n\n\u003e If your platform isn't x64, you can [build](./docs/build/index.md) by yourself or deploy by [source code](./docs/run_by_source_code/index.md).\n\n```sh\n./cicada start\n```\n\nNow cicada is available on `localhost:8000` or `{{ip}}:8000`. You can get more options by running `cicada start -h` or `cicada -h`.\n\n### Docker\n\n```sh\ndocker run \\\n  -d \\\n  --restart=always \\\n  -p 80:8000 \\\n  -v \u003cdata\u003e:/data \\\n  --name cicada \\\n  mebtte/cicada:v2 \\\n  start --port 8000 --data /data\n```\n\nYou can use `--user {uid}:{gid}` to map user.\n\n### Docker Compose\n\n```yml\nservices:\n  cicada:\n    restart: always\n    container_name: cicada\n    image: mebtte/cicada:v2\n\n    # user mapping\n    # user: 1000:1000\n\n    command: start --port 8000 --data /data\n    ports:\n      - 80:8000\n    volumes:\n      - /path/data:/data\n```\n\n## Migration\n\n### From v1 to v2\n\nIf you migrate to v2 from v1, you must upgrade data before serving:\n\n#### Binary\n\n```sh\ncicada upgrade-data \u003cdata\u003e\n```\n\n#### Docker:\n\n```sh\ndocker run -it --rm -v \u003cdata\u003e:/data mebtte/cicada:v2 upgrade-data /data\n```\n\n#### Other versions\n\n- [From v0 to v1](https://github.com/mebtte/cicada/tree/v1#from-v0-to-v1)\n\n## Music import\n\nYou can use `cicada import` to import music file or music directory. If Cicada can get music tags from the file, it will be imported. If not, it will be ignored.\n\n### Binary\n\n```sh\n# import direcoty\ncicada import --data /path_to/cicada_data --recursive \u003cmusic_directory\u003e\n\n# import file\ncicada import --data /path_to/cicada_data \u003cmusic\u003e\n```\n\n### Docker\n\n```sh\n# import directory\ndocker run -it --rm -v \u003cdata\u003e:/data -v \u003cmusic_directory\u003e:/source mebtte/cicada:v2 import --data /path_to/cicada_data --recursive /source\n\n# import file\ndocker run -it --rm -v \u003cdata\u003e:/data -v \u003cmusic_directory\u003e:/source mebtte/cicada:v2 import --data /path_to/cicada_data --recursive /source/\u003cmusic\u003e\n```\n\n## Data fixing\n\nAccording to known issues, some old versions of cicada will breakdown the data, you can fix it by using below command:\n\n```sh\ncicada fix-data \u003cdata\u003e\n```\n\nThis command is unharmful, so you can run it even the data isn't broken. Also can run the command by docker:\n\n```sh\ndocker run -it --rm -v \u003cdata\u003e:/data mebtte/cicada:v2 fix-data /data\n```\n\n## Development\n\nCicada is a **monorepo** that contains two sub-projects under the `apps` directory. `cli` is for the server, which is used to manage assets and start services. `pwa` is for the client, which is used to access for users. And there is a `shared` directory on the root, which contains the code runs on both `cli` and `pwa`.\n\nIf you want to develop or contribute, **most of cicada is developed by TS/JS** and you should know it. Cicada relies on [Node\u003e=18](https://nodejs.org) and you should install it on your device first.\n\nClone the project:\n\n```sh\ngit clone https://github.com/mebtte/cicada.git\n```\n\nInstall the dependencies:\n\n```sh\nnpm install\n```\n\nUse commands of cicada CLI:\n\n```sh\nnpm start -- -- \u003ccommand\u003e \u003coptions\u003e \u003carguments\u003e\n```\n\nBefore developing PWA, you should start dev server first:\n\n```sh\nCICADA_DATA=\u003cdata\u003e npm run dev:server\n# CICADA_DATA is the directory of data\n```\n\nModify the code of `cli` and the cicada server will restart automatically. Then open another terminal window and start the pwa server:\n\n```sh\nnpm run dev:pwa\n```\n\nVisit `localhost:8001` and use `http://localhost:8000` as server address, modify the code of `pwa` and you will see the change after auto reload.\n\nThere are useful documentations:\n\n- [Cicada API](https://www.postman.com/cicada-player)\n\n### Contributor\n\n\u003ca href=\"https://github.com/mebtte/cicada/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=mebtte/cicada\" /\u003e\n\u003c/a\u003e\n\n## Q \u0026 A\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow to migrate data?\u003c/summary\u003e\n\nAll of data is under `{{data}}` directory, copy or move it to new device.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eHow to login if I forget the password ?\u003c/summary\u003e\n\n1. If you are a normal user, you should contact the admin and let him/her help you to change the password. Above operation will also disable 2FA for your account.\n2. If you are an admin, you can let other admins help you to change the password or update the sqlite database using below SQL:\n\n```sql\nUPDATE user SET password = \u003cmd5\u003cmd5\u003cpassword\u003e\u003e\u003e WHERE username = \u003cusername\u003e;\nUPDATE user SET twoFASecret = NULL WHERE username = \u003cusername\u003e;\n```\n\n\u003c/details\u003e\n\n## License\n\n[GPL](./license)\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=mebtte/cicada\u0026type=Date)](https://star-history.com/#mebtte/cicada\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmebtte%2Fcicada","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmebtte%2Fcicada","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmebtte%2Fcicada/lists"}