{"id":13676210,"url":"https://github.com/AnnulusGames/LucidAudio","last_synced_at":"2025-04-29T03:30:42.498Z","repository":{"id":148154123,"uuid":"589632252","full_name":"annulusgames/LucidAudio","owner":"annulusgames","description":"Simple audio player for unity","archived":false,"fork":false,"pushed_at":"2024-02-08T14:41:47.000Z","size":714,"stargazers_count":72,"open_issues_count":2,"forks_count":11,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-03T00:51:47.377Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/annulusgames.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}},"created_at":"2023-01-16T15:18:29.000Z","updated_at":"2025-03-24T21:42:32.000Z","dependencies_parsed_at":"2024-01-14T14:31:42.355Z","dependency_job_id":"c00667b7-6e39-4fbe-a659-33b868c8eef6","html_url":"https://github.com/annulusgames/LucidAudio","commit_stats":null,"previous_names":["yn01dev/lucidaudio","yn01-dev/lucidaudio","annulusgames/lucidaudio","nuskey8/lucidaudio"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FLucidAudio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FLucidAudio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FLucidAudio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annulusgames%2FLucidAudio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/annulusgames","download_url":"https://codeload.github.com/annulusgames/LucidAudio/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251426724,"owners_count":21587637,"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":"2024-08-02T13:00:20.282Z","updated_at":"2025-04-29T03:30:41.461Z","avatar_url":"https://github.com/annulusgames.png","language":"C#","readme":"# Lucid Audio\nSimple audio player for Unity\n\n\u003cimg src=\"https://github.com/AnnulusGames/LucidAudio/blob/main/Assets/LucidAudio/Documentation~/Header.png\" width=\"800\"\u003e\n\n[![license](https://img.shields.io/badge/LICENSE-MIT-green.svg)](LICENSE)\n\n[日本語版READMEはこちら](README_JP.md)\n\n## Overview\nLucid Audio is a library that handles audio playback in Unity. You can easily describe how to play and stop sounds, set callbacks, etc. using method chaining.\n\n### Features\n* Simple description method using method chaining\n* Advanced settings such as delays and callbacks\n* Play/stop timing can be linked to GameObject\n\n### Requirement\n* Unity 2019.4 or higher\n\n### Install\n1. Open the Package Manager from Window \u003e Package Manager\n2. \"+\" button \u003e Add package from git URL\n3. Enter the following to install\n   * https://github.com/AnnulusGames/LucidAudio.git?path=/Assets/LucidAudio\n\n\nor open Packages/manifest.json and add the following to the dependencies block.\n\n```json\n{\n    \"dependencies\": {\n        \"com.annulusgames.lucid-audio\": \"https://github.com/AnnulusGames/LucidAudio.git?path=/Assets/LucidAudio\"\n    }\n}\n```\n\n### Namespace\nWhen using Lucid Audio, add the following line at the beginning of the file.\n\n```cs\nusing AnnulusGames.LucidTools.Audio;\n```\n\n## Basic Usage\n\nUse LucidAudio class to play audio.\n\n```cs\npublic Audioclip clip;\n\nprivate void Start()\n{\n    // play sound effect\n    LucidAudio.PlaySE(clip);\n}\n```\n\nUse method chaining to set delays, callbacks, etc.\n\n```cs\n// After waiting for 1 second, play BGM with Volume 0.7 and display \"Complete!\"\nLucidAudio.PlayBGM(clip)\n    .SetVolume(0.7f)\n    .SetDelay(1f)\n    .OnComplete(() =\u003e Debug.Log(\"Complete!\"));\n```\n\nThese methods have an AudioPlayer class as a return value. If you want to pause the audio or change settings during playback, call AudioPlayer methods.\n\n```cs\nAudioPlayer player = LucidAudio.PlaySE(clip);\n\n// pause/resume audio\nplayer.Pause();\nplayer.UnPause();\n\n// play audio from beginning\nplayer.Restart();\n```\n\nUse FadeVolume or add an argument when playing/stopping to fade the volume.\n\n```cs\n\n// fade the first second\nAudioPlayer player = LucidAudio.PlayBGM(clip, 1f);\n\n// Change volume to 0.7 over 1 second\nplayer.FadeVolume(0.7f, 1f);\n\n// stop after 2 seconds fade out\nplayer.Stop(2f);\n```\n\n### Constraint\nAudioPlayer dispose its internal AudioSource when you call Stop, so it cannot be used again after stopping. Attempting to call Play or Restart on a stopped AudioPlayer will throw InvalidOperationException.\n\n```cs\nAudioPlayer player = LucidAudio.PlayBGM(clip);\n// stop playing audio\nplayer.Stop();\n\n// InvalidOperationException: A stopped AudioPlayer is not allowed to play again. You need to create a new AudioPlayer.\nplayer.Restart();\n```\n\nIf you want to play the stopped AudioPlayer again, use Pause instead of Stop.\n\nAlso, in the default setting, Stop is automatically called at the end. By setting SetAutoStop to false, you can set the AudioPlayer to return to its pre-play state when playback ends.\n\n```cs\nAudioPlayer player = LucidAudio.PlayBGM(clip)\n    .SetAutoPause(false);\n\n// Play, UnPause, and Restart can be used even after termination\nplayer.Play();\n\n// Explicitly call Stop when finished, as it is not automatically disposed\nplayer.Stop();\n```\n\n## Callbacks\nLucid Audio makes it easy to set callbacks using methods.\nBelow is a list of callbacks that can be set on the AudioPlayer.\n\n### OnStart\nCalled at the moment the audio starts playing. If a delay is set with SetDelay, it will be called when the delay ends.\n\n### OnPlay\nCalled every frame while audio is playing. Not called while paused.\n\n### OnPause\nCalled when the audio is paused.\n\n### OnComplete\nCalled when the audio has finished playing. It is not called if you stop playback with Stop.\n\n### OnStop\nCalled when the audio has stopped. Also called on completion if SetAutoStop is not set.\n\n## 3D Sound\nBy setting the value with SetSpatialBlend, you can play audio considering the distance to the sound source.\n\n```cs\n// Set Spatial Blend to 1\nLucidAudio.PlaySE(clip)\n    .SetSpatialBlend(1f);\n```\n\nUse SetPosition to specify the position of the sound source.\n\n```cs\n// play sound effect at position (1, 2, 3)\nLucidAudio.PlaySE(clip)\n    .SetSpatialBlend(1f)\n    .SetPosition(new Vector3(1f, 2f, 3f));\n```\n\nParameters such as Rolloff Mode and Max Distance can also be set using methods.\n\n```cs\nLucidAudio.PlaySE(clip)\n    .SetSpatialBlend(1f)\n    .SetPosition(new Vector3(1f, 2f, 3f))\n    .SetMaxDistanc(10f)\n    .SetRolloffMode(AudioRolloffMode.Logarithmic);\n```\n\n## Grouping\nBy setting an ID for AudioPlayer, multiple AudioPlayers can be handled collectively.\nUse SetID to set the ID.\n\n```cs\n// Set ID to AudioPlayer\nLucidAudio.PlaySE(clip)\n    .SetID(\"GroupName\");\n```\n\nIf you want to collectively manipulate audios with IDs, add the IDs to the arguments of the LucidAudio class methods.\n\n```cs\n// Stop all AudioPlayers whose ID is set to \"GroupName\"\nLucidAudio.StopAll(\"GroupName\");\n```\n\nAlso, by using GetPlayersByID, you can get all AudioPlayers with matching IDs.\n\n```cs\n// Get all AudioPlayers whose ID is set to \"GroupName\"\nAudioPlayer[] players = LucidAudio.GetPlayersByID(\"GroupName\");\n\n// Set Volume to 0.5\nforeach (AudioPlayer player in players)\n{\n    player.SetVolume(0.5f);\n}\n```\n\n## SetLink\nBy using SetLink, it is possible to link the audio playback/stop timing to the state of the GameObject.\n\n```cs\n// Call Stop when gameObject is destroyed\nLucidAudio.PlayBGM(clip)\n    .SetLink(gameObject);\n```\n\nBy specifying AudioLinkBehaviour as an argument, detailed behavior can be set. (Stop is called at OnDestroy regardless of which option is specified.)\n\n```cs\n// pause when inactive, play when active\nLucidAudio.PlayBGM(clip)\n    .SetLink(gameObject, AudioLinkBehaviour.PauseOnDisableUnPauseOnEnable);\n```\n\nAvailable options are:\n* StopOnDestroy\n* StopOnDisable\n* PlayOnEnable\n* RestartOnEnable\n* PauseOnDisable\n* PauseOnDisableUnPauseOnEnable\n* PauseOnDisableRestartOnEnable\n\n## Coroutines \u0026 async/await\nYou can also use coroutines or async/await to wait for audio to finish. To use AudioPlayer in coroutine, call WaitForCompletion.\n\n```cs\nIEnumerator Coroutine()\n{\n    // wait until playback ends\n    yield return LucidAudio.PlaySE(clip).WaitForCompletion();\n}\n```\n\nIt is also possible to convert to Task by using WaitForCompletionAsync.\n\n```cs\nasync void MethodAsync()\n{\n    // Convert to Task, wait until playback ends\n    await LucidAudio.PlaySE(clip).WaitForCompletionAsync();\n}\n```\n\n### UniTask\n\nLucidAudio supports UniTask. ToUniTask becomes available by introducing UniTask to the project from Package Manager.\n\n```cs\nasync UniTask MethodAsync(CancellationToken token = default)\n{\n    try\n    {\n        // Convert to UniTask, wait until playback ends\n        await LucidAudio.PlaySE(clip).ToUniTask(cancellationToken: token);\n    }\n    catch (OperationCanceledException ex)\n    {\n        Debug.Log(\"Canceled\");\n    }\n}\n```\n\nAlso, you can set the behavior when canceling by specifying AudioCancelBehaviour as an argument. (Stop is set by default)\n\n```cs\nasync UniTask MethodAsync(CancellationToken token = default)\n{\n    try\n    {\n        // Pause AudioPlayer on cancel\n        await LucidAudio.PlaySE(clip).ToUniTask(AudioCancelBehaviour.Pause, cancellationToken: token);\n    }\n    catch (OperationCanceledException ex)\n    {\n        Debug.Log(\"Canceled\");\n    }\n}\n```\n\n## ライセンス\n\n[Mit License](LICENSE)\n\n\n","funding_links":[],"categories":["Open Source Repositories"],"sub_categories":["Audio Manager"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAnnulusGames%2FLucidAudio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAnnulusGames%2FLucidAudio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAnnulusGames%2FLucidAudio/lists"}