Feature/audio

[pilunte23]

Audio System Update

This change adds support for a larger, structured audio system for gameplay sound effects.

The previous implementation only handled a few simple audio files. After adding many card-specific and generic sounds, the audio lookup needed to support nested directories, multiple variants, .ogg files, and optional CDN hosting for large audio assets.

Main Changes

• Added audio cue resolution through frontend/public/audio/manifest.json.
• Added support for .ogg, .mp3, and .wav files.
• Converted local audio assets from .wav to .ogg to reduce file size.
• Regenerated the audio manifest so it now points to .ogg files.
• Added AUDIO_HOST support, following the same local/CDN philosophy used for image assets.
• Mounted local audio files and the audio manifest into the Docker web container.
• Fixed local playback by allowing the local instance to resolve audio through /audio/....
• Added gameplay audio triggers for:
  • Playing cards
  • Exhausting cards
  • Discarding cards
  • Flipping or revealing locations
  • Removing uses/resources from cards, including firearm ammo
  • Investigator movement
  • Enemy movement, including card-specific sounds such as Ghoul Priest

Audio Directory Structure

Audio files are stored under:

frontend/public/audio/
├── manifest.json
├── turnIndicator.ogg
├── impactPunch_heavy_000.ogg
└── cards/
    ├── Generic/
    │   ├── Mini/
    │   │   ├── Mini (1).ogg
    │   │   ├── Mini (2).ogg
    │   │   ├── Mini (3).ogg
    │   │   ├── Mini (4).ogg
    │   │   └── Mini (5).ogg
    │   ├── moveCard/
    │   │   └── Humanoid.ogg
    │   ├── playCard/
    │   │   ├── Firearm.ogg
    │   │   ├── Spell.ogg
    │   │   └── ...
    │   └── removeResourceCard/
    │       ├── Firearm.ogg
    │       └── ...
    └── Specific/
        ├── moveCard/
        │   └── Ghoul Priest.ogg
        ├── flipCard/
        │   ├── Attic.ogg
        │   ├── Cellar.ogg
        │   └── ...
        ├── playCard/
        │   └── ...
        ├── exhaustCard/
        │   └── ...
        └── discardCard/
            └── ...
            
            
Cue Resolution
The backend resolves audio cues using the generated manifest.

For card-related sounds, it first tries to find a specific sound for the card title:

If no specific sound exists, it falls back to generic sounds based on the card traits:

For example, when the Ghoul Priest moves, the backend tries:

For investigator movement, the backend uses the generic mini movement cue:

When multiple variants exist for the same cue, one variant is selected randomly.

Asset Hosting
Large audio files are handled with the same philosophy as image assets.

In development, audio files can be mounted locally:


In production, they can be served from the CDN through AUDIO_HOST.

The small manifest file should stay in the repository:


This allows the backend to resolve cue names without requiring the full audio library to be included in the Docker image or committed to Git.

Local Docker Setup
For local development, the Docker web service mounts both the audio manifest and the audio card files:


The local instance can force local audio resolution with:


This makes the frontend resolve audio paths through:


Development Note
This work was mostly vibe coded with AI assistance, then validated through local Docker rebuilds, manifest checks, and HTTP checks against the generated .ogg audio files. 

## Sharing the Sound Library

I can obviously share my current sound library with you and with the community.

Most of the files are already organized by gameplay action, card title, or trait, so they should be easy to reuse, review, or extend. Sharing them may also motivate me to keep expanding the collection with more card-specific and thematic sounds over time.

The current structure is designed so new sounds can be added incrementally:

```text
frontend/public/audio/cards/
├── Generic/
│   └── <action>/<trait>.ogg
└── Specific/
    └── <action>/<card title>.ogg

[pilunte23]

I 'm admin on french HAA discord , you can find me here easily
https://discord.gg/A23rum4

[pilunte23]

https://cloud.davops.fr/s/nZrDxQS67wBwknz

[halogenandtoast]

Hi again @pilunte23

Unfortunately this is another PR I won't merge in. Part of the reason is the same, if I accept this I need to maintain it moving forward and adding this much sound integration is a lot to take on all at once. I would much rather prefer more targeted choices about which sounds to include and to grow the system a bit more organically.

With the 2 sounds I have now I don't need to manage much, but as you've taken on in this PR, if there are a bunch I then need to manage assets in a more complex way.

I think if there were some specific sounds that greatly improved quality of life now, or had very strong thematic ties to the cards (like the labyrinths of lunacacy cards I added it for), then I would be happy to start there.

I would also need to make sure the sounds had appropriate licenses for usage (again see the labyrinths of lunacy example).

Again I hope me closing this PR does dissuade you from future contributions (or even refining this one based on my feedback).

Thanks again and I hope you continue to enjoy the app!

[pilunte23]

@halogenandtoast
Regarding the previous PR, I understand.

On this one, I confess I understand the explanation less.

With the system I'm proposing, you have the possibility of playing specific sounds depending on the map and the action performed (drawing out a gun is not the same as firing it).

Furthermore, precisely to avoid constantly updating sounds, if a specific sound isn't implemented, you have generic sounds based on traits, which quickly covers a large number of maps (and naturally, newly implemented maps). This allows you to take your time implementing specific sounds.

Have you had a chance to try this PR?

I coded this for OCTGN. I find it a shame not to be able to use the sounds in the Arkham app, but you are obviously in charge of your application.

[halogenandtoast]

Hi @pilunte23

With the system I'm proposing, you have the possibility of playing specific sounds depending on the map and the action performed (drawing out a gun is not the same as firing it).

Understood, I like the flexibility of the system.

Furthermore, precisely to avoid constantly updating sounds, if a specific sound isn't implemented, you have generic sounds based on traits, which quickly covers a large number of maps (and naturally, newly implemented maps). This allows you to take your time implementing specific sounds.

Right, I understand.

For some context here I think I need to frame my thoughts better. Sounds are a relatively new thing I just added to the system (driven primarily by people wanting an audio indication that it is their turn). The only other sound I currently have is thematically tied to a specific scenario which is currently in public alpha. As it is relatively a new system, I haven't given a lot of thought yet about how I want it to evolve and because of that I don't want to develop it too rapidly over something slower and thought out, but I do agree that sounds can increase the immersion and furthermore are something that a digital solution can improve on over the physical version.

However, as part of designing this system there are some things I have been given a lot of thought to on how to evolve the system moving forward:

a) Sounds aren't really a backend concern, they're a frontend concern, so I would actually like to design a way that the backend is primarily unaware the audio exists and is instead communicating events to the frontend, which can handle them how they want (audio, animations, etc.)
b) Because there are often many moving parts during interactions, I haven't given a lot of thought about how audio might layer (if 15 things change, do I play 15 sounds, do I prioritize 1, etc.). With only 2 audio files that are not likely to overlap I haven't had to worry about this problem, but at a larger scale I might
c) I also need to work in audio settings so they can easily be enabled/disabled so there is a bit of UI work I would need to do. For instance a user might want the turn notification, but not other sounds. Maybe these sounds need some sort of volume control, etc.

I think with all of these things it's a bit easier to make architectural decisions and find a good solution before I bring such a system into the app.

If you were interested in seeing this work make progress I think it would be a good idea to discuss/work with me on the audio settings and controls first, then figure out a better event system between the frontend/backend so that the backend doesn't really have to manage audio at all, then start extending that system on the frontend with the most impactful cases gradually and see how they land with people.

I hope this provides some clarity as to why I closed this specific PR and that I am not closed to the idea or even some parts of this implementation, I would happily transfer the ideas here into the envisioned system (or accept PRs that do so).

[pilunte23]

thanks for the explanation @halogenandtoast
I understand that this feature does not take priority over the content of the game. that's why I wanted to try to humbly help.
I see better what you want now, so my question is "how can I help you with this audio feature?"
I remain at your disposal
Kind regards
Pilunte