{"id":24443720,"url":"https://github.com/endlessm/hack-sound-server","last_synced_at":"2025-03-14T03:14:01.774Z","repository":{"id":56665892,"uuid":"154541463","full_name":"endlessm/hack-sound-server","owner":"endlessm","description":"Service to play sounds on behalf of Endless Hack applications","archived":false,"fork":false,"pushed_at":"2022-03-03T10:22:21.000Z","size":191274,"stargazers_count":2,"open_issues_count":9,"forks_count":0,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-01-20T22:17:07.634Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/endlessm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-24T17:29:54.000Z","updated_at":"2024-11-01T18:44:33.000Z","dependencies_parsed_at":"2022-08-15T22:50:56.103Z","dependency_job_id":null,"html_url":"https://github.com/endlessm/hack-sound-server","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endlessm%2Fhack-sound-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endlessm%2Fhack-sound-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endlessm%2Fhack-sound-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/endlessm%2Fhack-sound-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/endlessm","download_url":"https://codeload.github.com/endlessm/hack-sound-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243515565,"owners_count":20303258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-01-20T22:17:14.599Z","updated_at":"2025-03-14T03:14:01.755Z","avatar_url":"https://github.com/endlessm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hack-sound-service\nThis is a dbus-based server that plays sounds given a metadata file and a bunch of sound files.\n\n# Getting started\nTo test this project, please follow these steps:\n\n## 1. Clone the repository\nOpen a terminal. In Endless OS, search \"terminal\" in the desktop, to find and open a terminal. Then, type the following command:\n```\ngit clone https://github.com/endlessm/hack-sound-server/\ncd hack-sound-server/\n```\n## 2. Build and install the server\nTo build and install you can use the build-flatpak.sh script in the root directory. It will build the current branch and install the flatpak directly.\n```\n./build-flatpak.sh\n```\nIf a password is requested, input it.\n\n## 3. Play a sound!\nJust type this following command in the terminal to play a sound:\n```\ngdbus call --session --dest com.hack_computer.HackSoundServer --object-path /com/hack_computer/HackSoundServer --method com.hack_computer.HackSoundServer.PlaySound framework/piano/1\n```\n\nSounds are registered internally by a tag known as the \"sound event id\". The server includes these following sound event ids available:\n```\nframework/drumkit/0\nframework/drumkit/1\nframework/drumkit/2\nframework/drumkit/3\nframework/drumkit/4\nframework/drumkit/5\nframework/piano/0\nframework/piano/1\nframework/piano/2\nframework/piano/3\nframework/piano/4\nframework/piano/5\nframework/scifi/0\nframework/scifi/1\nframework/scifi/2\nframework/scifi/3\nframework/scifi/4\nframework/scifi/5\n```\nThe previously listed sound event ids are specified in a metadata file located at `data/sounds/metadata.json`. More descriptions about the metadata file will be explained in the next section.\n\u003e Do not think that there is a pattern for sound event ids. For example, `framework/scifi/5` is just a a string, it could have been called `scifi-5WhatEver`, too.\n\n# Metadata file\nMetadata files describe the behavior of sounds. The **hack-sound-server** reads from the metadata file to know what sounds are available and to know how to play them. The default metadata that the **hack-sound-server** uses is located at `data/sounds/metadata.json`.\n\u003e Do not edit this file if you are just testing the sounds. Instead override it (more detauls in the next subsection).\n\nAn example of metadata file is the following:\n```\n{\n    \"framework/drumkit/0\": {\n        \"sound-file\": \"drumkit/176980__snapper4298__kick-2-with-start.wav\",\n        \"license\": \"CC-BY\",\n        \"source\": \"freesound.org\"\n    },\n    \"framework/piano/0\": {\n        \"sound-file\": \"piano/39177__jobro__piano-ff-030.wav\",\n        \"license\": \"CC-BY\",\n        \"source\": \"freesound.org\"\n    }\n```\nThis metadata file specifies two sound event ids: `framework/drumkit/0` and `framework/piano/0`. Then each entry, tells what is the location of the audio file (`sound-file`), the license of the sound (`license`) and the source where it was obtained from (`source`).\n\n## A full example\n```\n{\n    \"example/sound/1\": {\n        \"sound-file\": \"sound0.wav\",\n        \"sound-files\": [\n            \"sound1.wav\",\n            \"sound2.wav\",\n            \"sound3.wav\"\n        ],\n        \"loop\": true,\n        \"fade-in\": 3000,\n        \"fade-out\": 5000,\n        \"volume\": 0.5,\n        \"pitch\": 2.0,\n        \"delay\": 10000,\n        \"overlap-behavior\": \"restart\"\n    }\n}\n```\nThis example shows all the options that the metadata file accepts.\n\n- **`sound-file`**: Indicates the path to the sound file to be played.\n- **`sound-files`**: It's an array of paths, and indicates that one of these sounds should be picked up randomly to be played. If like in this example, `sound-file` and `sound-files` are set, then all the specified paths will be considered. In other words, for this example, one sound among \"sound0.wav\", \"sound1.wav\", \"sound2.wav\" and \"sound3.wav\" would be played.\n- **`loop`**: If set to `true` the sound will be played again when it finishes. *Defaults to `false`*.\n- **`fade-in`**: Indicates the time duration in which the volume of the sound should fade in from the start. The used unit is milliseconds. *Defaults to 1000 only if `loop` is set to `true`*.\n- **`fade-out`**: Indicates the time duration in which the volume of the sound should fade out after the sound is stopped. The used unit is milliseconds. *Defaults to 1000 only if `loop` is set to `true`*.\n- **`volume`**: Indicates the volume level the sound you play at. *Defaults to 1.0 (the \"normal\" volume)*.\n- **`pitch`**: Sets the sound pitch while keeping the original tempo (speed). *Defaults to 1.0 (the \"normal\" pitch)*.\n- **`rate`**: Sets the tempo and pitch. *Defaults to 1.0 (the \"normal\" rate)*.\n- **`delay`**: The duration in milliseconds that should be delayed before the sound starts. *Defaults to 0*.\n- **`overlap-behavior`**: Indicates the behavior of the sound when the same sound is requested to be played while the other is also playing. The available options are: `\"overlap\"`, `\"ignore\"` and `\"restart\"`. If `\"overlap\"` is set, then if the same sound is played twice or more times simultaneously, all these sounds will overlap between them. If `\"ignore\"` is set, if the target sound is already playing and an application requests to play this sound, this request will be ignored: this means that **only one** instance of the sound will be played. If `\"restart\"` is set, then if the target sound is already playing and an application requests to play this sound, the sound will be restarted: this (also) means that **only one** instance of the sound will be playing. *Defaults to `\"overlap\"`*.\n- **`type`**: There are two types of sounds: `\"bg\"` and `\"sfx\"`. Sounds of `bg` type follow a special logic: if another `bg` sound is currently playing back and a new `bg` sound is requested to play back, then the last `bg` sound will pause and the new sound will play back. Sounds of type `sfx` are just all the rest. *Defaults to `\"sfx\"`*\n\n## Overriding the metadata file\nTo override metadata files or add more sounds, you can create your own metadata file. **All the sounds specified there will have the highest priority**.\n\nCreate a file in the following path `$HOME/.var/app/com.hack_computer.HackSoundServer/data/metadata.json`.\n\u003e `$HOME` represents your home directory.\n\u003e `.var` is a hidden directory. You can show hidden files with the keys `ctrl` + `h` in the Endless OS file browser.\n\nOnce you have created that file, you can add for example the following content:\n```\n{\n    \"water\": {\n        \"sound-file\": \"water.wav\"\n    },\n    \"framework/piano/0\": {\n        \"sound-file\": \"beep.wav\",\n    }\n}\n```\n\u003e Beware of closing curly braces properly.\n\nThen you should create the folder `sounds` in `$HOME/.var/app/com.hack_computer.HackSoundServer/data/` and put your sounds files there. In this case, you would have to put the sound file `water.wav` and `beep.wav`.\n\n### Playing sounds\nYou can test the `water` sound event id when you input this command in a terminal:\n```\ngdbus call --session --dest com.hack_computer.HackSoundServer --object-path /com/hack_computer/HackSoundServer --method com.hack_computer.HackSoundServer.PlaySound water\n```\n\nIf you run the following command on a terminal, this will actually play the sound `beep.wav` because it was specified so in your metadata file.\n```\ngdbus call --session --dest com.hack_computer.HackSoundServer --object-path /com/hack_computer/HackSoundServer --method com.hack_computer.HackSoundServer.PlaySound framework/piano/1\n```\n### Stop a sound\nWhen you input the previous commands to play a sound you must have seen that something like the following has been output:\n```\n('a72276d2-a856-4531-aac1-59fe1d331fc1',)\n```\nThis is the identifier of the sound you have told to play and you can use it to stop it.\n```\ngdbus call --session --dest com.hack_computer.HackSoundServer --object-path /com/hack_computer/HackSoundServer --method com.hack_computer.HackSoundServer.StopSound a72276d2-a856-4531-aac1-59fe1d331fc1\n```\n\n# Logging\n\n## Log levels\nThe default log level is WARNING, which means that by default only WARNING,\nERROR and CRITICAL levels will be logged.\n\nThe log level can be set using the environment variable `HACK_SOUND_SERVER_LOGLEVEL`.\n\nTo log everything:\n```\nHACK_SOUND_SERVER_LOGLEVEL=0 flatpak run com.hack_computer.HackSoundServer\n```\n\nOr for example, to log levels from INFO and upper:\n```\nHACK_SOUND_SERVER_LOGLEVEL=INFO flatpak run com.hack_computer.HackSoundServer\n```\n\nFor more information about levels, check the [Python logging system documentation](https://docs.python.org/3/library/logging.html).\n\n## Format\nFor example, the following log output\n\n```\nDEBUG    : 2019-01-29 09:35:52,176 \u003cHackSoundServer at 139708402141224\u003e.ref - :1.19, :1.20: clubhouse/entry/hover: a1881470-0d54-4e1a-a4bd-3ca76a648ebf: Reference. Refcount: 1 (server.py:382)\n```\n\nshould be interpreted as:\n\n- `DEBUG`: The log level\n- `2019-01-29 09:35:52,176`: The current date and time\n- `\u003cHackSoundServer at 139708402141224\u003e`: The class and id of the object from which the log is called.\n- `.ref`: The method that called the log instruction.\n- `:1.19, :1.20:`: The unique bus names that referenced the sound.\n- `clubhouse/entry/hover`: The sound event id.\n- `a1881470-0d54-4e1a-a4bd-3ca76a648ebf`: The uuid.\n- `Reference. Refcount: 1`: The log message.\n- `(server.py:382)`: The file and line from which the log instruction was called.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fendlessm%2Fhack-sound-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fendlessm%2Fhack-sound-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fendlessm%2Fhack-sound-server/lists"}