set_volume_per_voice(3)

🎀 NAME 🎀

set_volume_per_voice — bestie, it sets the volume of a voice. It's part of the Allegro game programming library, and it's literally the knob you reach for when your mix sounds crunchy. 💅

---

✨ SYNOPSIS ✨

#include <allegro.h>

void set_volume_per_voice(int scale);

---

🌸 DESCRIPTION 🌸

okay so here's the tea. By default, Allegro will play a centred sample at half volume on both the left and right channel. But a sample panned all the way to the far right or far left? That one plays at maximum volume on that channel only. Why tho? So you can play a single panned sample without distortion, that's why. 🦋

But the second you start playing multiple samples at full volume, the mixing process can result in clipping — which is a very noticeable form of distortion, and ngl it's giving crunchy-garbage audio. The more samples you play, the more likely clipping is to occur, and the more clipping there is, the worse the output is gonna sound. it's math, it's vibes, it's math-vibes. 💀

So if clipping is a problem — or lowkey if the output is just too quiet — this function is the one you call to adjust the volume of each voice. But before you do, do the vibe check first:

• make sure your speakers are at a reasonable volume,
• make sure Allegro's global volume is at maximum (see set_volume() below),
• and make sure any other mixers, like the Windows Volume Control, are set reasonably too.

Once you're sure that Allegro's output level is unsuitable for your application, then, and only then, use this function to adjust it. 👑

Here's the magic: each time you increase the parameter by one, the volume of each voice will halve. So for example, if you pass 4, you can play up to 16 centred samples at maximum volume without distortion. cute, right? 🍓

If you pass 0 to this function, each centred sample will play at the maximum volume possible without distortion, and so will all samples played through a mono driver. But samples at the extreme left and right will distort if played at full volume. So if you wish to play panned samples at full volume without distortion, you should pass 1 to this function.

Note: this is different from the function's behaviour in WIPs 3.9.34, 3.9.35 and 3.9.36. If you used this function under one of these WIPs, you will have to increase your parameter by one to get the same volume. not a drill, bestie, go bump that number. 🙈

Note: The default behaviour has changed as of Allegro 4.1.15. If you would like the behaviour of earlier versions of Allegro, pass -1 to this function. Allegro will choose a value dependent on the number of voices, so that if you reserve n voices, you can play up to n/2 normalised samples with centre panning without risking distortion. The exception is when you have fewer than 8 voices, where the volume remains the same as for 8 voices.

Here are the values, dependent on the number of voices:

• 1-8 voices — set_volume_per_voice(2)
• 16 voices — set_volume_per_voice(3)
• 32 voices — set_volume_per_voice(4)
• 64 voices — set_volume_per_voice(5)

And of course, this function does not override the volume you specify with play_sample() or voice_set_volume(). It simply alters the overall output of the program. Which means if you play samples at lower volumes, or if they aren't normalised, you can play more of them without distortion. slay. 🔥

It is recommended that you hard-code the parameter into your program, rather than offering it to the user. The user can alter the volume with the configuration file instead, or you can provide for this with set_volume(). don't make your users do your job for you, it's not their moment. 😭

To restore volume per voice to its default behaviour, pass 1. periodt. 💖

---

👑 SEE ALSO 👑

• reserve_voices(3)
• set_volume(3)
• install_sound(3)
• detect_digi_driver(3)
• detect_midi_driver(3)

---

okay that's the whole page bestie, mwah 🫶 this iconic lil manual moment comes to you courtesy of Allegro, version 4.4.3 — go forth and mix without clipping, you got this ✨🎀💜