{"id":46662837,"url":"https://github.com/thatcakey/aural","last_synced_at":"2026-03-08T14:01:54.595Z","repository":{"id":342709001,"uuid":"1174815898","full_name":"ThatCakey/Aural","owner":"ThatCakey","description":"Crossplatform Audio Wrapper for dotnet simplifying playing an audio file into a single line of code ","archived":false,"fork":false,"pushed_at":"2026-03-06T23:48:37.000Z","size":10,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-07T04:40:56.746Z","etag":null,"topics":["audio","dotnet","linux","macos","nuget-package","ogg-vorbis","openal","wav","windows"],"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/ThatCakey.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":null,"dco":null,"cla":null}},"created_at":"2026-03-06T21:51:05.000Z","updated_at":"2026-03-06T23:59:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ThatCakey/Aural","commit_stats":null,"previous_names":["thatcakey/aural"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ThatCakey/Aural","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThatCakey%2FAural","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThatCakey%2FAural/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThatCakey%2FAural/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThatCakey%2FAural/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThatCakey","download_url":"https://codeload.github.com/ThatCakey/Aural/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThatCakey%2FAural/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30260028,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T08:59:44.879Z","status":"ssl_error","status_checked_at":"2026-03-08T08:58:02.867Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["audio","dotnet","linux","macos","nuget-package","ogg-vorbis","openal","wav","windows"],"created_at":"2026-03-08T14:01:49.794Z","updated_at":"2026-03-08T14:01:54.578Z","avatar_url":"https://github.com/ThatCakey.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aural\n\n**Audio playback library for .NET** — Play audio files with a single line of code using cross-platform OpenAL support.\n\n[Aural is on NuGet](https://www.nuget.org/packages/Aural)\n\n## Features\n\n- **Simple API**: Play any audio file with `Player.Play(path, volume, loop)`\n- **Cross-platform**: Works on Windows, macOS, and Linux automatically\n- **Format support**: WAV, OGG Vorbis, MP3\n- **Playback control**: Pause, resume, stop, volume adjustment, seeking\n- **Zero setup**: No initialization required—just start playing\n- **Intuitive tokens**: Control-based API via PlaybackToken objects\n- **Real-time filters**: Low-pass, high-pass, reverb, and pitch shift (opt-in for zero overhead)\n- **OpenAL backend**: Built on OpenTK.Audio.OpenAL for reliable, cross-platform audio\n\n## Installation\n\n```bash\ndotnet add package Aural\n```\n\n## Quick Start\n\n```csharp\nusing Aural;\n\n// Play an audio file\nvar token = Player.Play(\"path/to/song.mp3\", 0.7f, loop: true);\n\n// Let it play for 10 seconds\nThread.Sleep(10000);\n\n// Pause playback\ntoken.Pause();\nThread.Sleep(10000);\n\n// Resume playback\ntoken.Play();\nThread.Sleep(10000);\n\n// Stop and release resources\ntoken.End();\n\n// Optional: cleanup all active playbacks on shutdown\nPlayer.Dispose();\n```\n\n## Audio Effects\n\nApply real-time filters to audio playback. All filters are disabled by default (zero performance cost). Enable only the filters you need.\n\n### Supported Filters\n\n- **Low-Pass**: Removes high frequencies (~0.5ms overhead)\n  - Parameters: `Frequency` (20-20000 Hz), `Resonance` (0.5-5.0 Q)\n  - Use case: Warm tone, remove noise\n\n- **High-Pass**: Removes low frequencies (~0.5ms overhead)\n  - Parameters: `Frequency` (20-2000 Hz), `Resonance` (0.5-5.0 Q)\n  - Use case: Remove rumble, sub-bass\n\n- **Reverb**: Schroeder reverberator for room ambience (~3-5ms overhead)\n  - Parameters: `RoomSize` (0.0-1.0), `DampFactor` (0.0-1.0), `Wet` (0.0-1.0), `Dry` (0.0-1.0)\n  - Use case: Space, ambience\n\n- **Pitch Shift**: STFT phase vocoder for transposition (~10-15ms overhead, **50-200ms latency**)\n  - Parameters: `SemiTones` (-12 to +12), `WindowSize` (512, 1024, 2048)\n  - Use case: Transpose music, karaoke, tuning adjustment\n\n### Filter Example\n\n```csharp\nusing Aural;\nusing Aural.Filters;\n\n// Create audio effect with filters\nvar effect = new AudioEffect\n{\n    LowPass = new LowPassFilter\n    {\n        Enabled = true,\n        Frequency = 8000f,    // Remove frequencies above 8kHz\n        Resonance = 1.0f\n    },\n    Reverb = new ReverbFilter\n    {\n        Enabled = true,\n        RoomSize = 0.7f,       // Larger room\n        DampFactor = 0.5f,     // Dampen high frequencies\n        Wet = 0.3f,            // 30% reverb mix\n        Dry = 0.7f             // 70% original signal\n    }\n};\n\n// Apply effects during playback\nvar token = Player.Play(\"song.mp3\", volume: 0.8f, effect: effect);\n\n// Query which filters are active\nvar activeEffects = token.GetActiveFilters();\nConsole.WriteLine($\"Low-Pass: {activeEffects.LowPass.Enabled}\");\nConsole.WriteLine($\"Reverb: {activeEffects.Reverb.Enabled}\");\n\nThread.Sleep(5000);\ntoken.End();\n```\n\n### Important Notes\n\n- **Immutability**: The effect object is **deep-cloned** when playback starts. Modifications after `Play()` have no effect.\n- **Opt-In**: Filters are disabled by default. Enable only what you need.\n- **Pitch Shift Latency**: Expect 50-200ms latency with pitch shift enabled. Use smaller `WindowSize` for lower latency, larger for better quality.\n- **Cross-Platform**: All filters work identically on Windows, macOS, and Linux.\n\n## API Reference\n\n### `Player.Play(filePath, volume, loop, effect)`\n\nPlays an audio file and returns a PlaybackToken for control.\n\n**Parameters:**\n- `filePath` (string): Path to audio file (WAV, MP3, OGG)\n- `volume` (float, default: 1.0): Volume level 0.0 (silent) to 1.0 (full)\n- `loop` (bool, default: false): Whether to loop the audio\n- `effect` (AudioEffect?, default: null): Optional audio effects/filters to apply\n\n**Returns:** `PlaybackToken?` - Control token, or null if playback failed\n\n### `PlaybackToken` Methods\n\n- `Pause()` - Pause playback\n- `Play()` - Resume playback\n- `End()` - Stop and release resources\n- `SetVolume(float)` - Adjust volume (0.0-1.0)\n- `Seek(float)` - Seek to position in seconds\n- `GetActiveFilters()` - Get reconstructed AudioEffect showing which filters are active\n- `IsPlaying` (property) - Check if audio is playing\n- `CurrentPosition` (property) - Get current playback position in seconds\n- `Duration` (property) - Get total audio duration in seconds\n\n### `Player.Dispose()`\n\nDisposes all active playback sessions. Call on application shutdown.\n\n## Supported Formats\n\n- WAV (.wav)\n- OGG (.ogg)\n- MPEG (.mp3)\n\n## Platform Support\n\n- Windows\n- macOS\n- Linux\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthatcakey%2Faural","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthatcakey%2Faural","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthatcakey%2Faural/lists"}