VUMeter

VU 53.7 (12/28/2023)
©28.12.2023 Lyle Hazelwood, all rights reserved

VU ?
L=LEFTEDGE/N,T=TOPEDGE/N,W=WIDTH/N,H=HEIGHT/N,WINTITLE/K,DEPTHGAD/S,
DRAGGAD/S,CLOSEGAD/S,SIZEGAD/S,P=PUBSCREEN/K,V=VERBOSE/S,
I=INLINKNAME/K,B=BACKGROUND/K,F=FOREGROUND/K,PEAKCOLOR/K,LEGENDS/S,
VU/S,DAMPINGUP/N,DAMPINGDOWN/N,FIRSTCHANNEL/N,LOWMETER/N,HIGHMETER/N,
C=CHANNELS/N: 

Added arguments for window gadgets,
DEPTHGAD/S, DRAGGAD/S,CLOSEGAD/S,SIZEGAD/S
These all default to FALSE, so if you don't ask for a gadget, you 
don't get it.

Added PEAKCOLOR, which if specified will create a peak hold marker
showing the highest amplitude of each channel.

Added support for iconification, which prevents problems when
changing screenmodes. Iconification will copy the program icon
if it finds one.

Added an icon that looks something like a VU meter.

Restructured the whole program to move out of globals and into
structures, to keep things neat and easier to manage. This also
corrected a bug when channels is greater than 2.

////////////////////////////////////////////////////////
VU 53.3 (12/16/2023)
©16.12.2023 Lyle Hazelwood, all rights reserved

A simple Audio Level Meter


Displays Audio Level information on a 2 channel vertical bargraph display.
Configurable size, color, and ballistics.

Gets audio level information by CAMD, using MIDI messages.

The X1000 and A1222 audio drivers can provide these messages if enabled.
You can also build an external arduino powered transmitter if desired.


/**************** Quick Start: *********************/
Copy VU to wherever you want it.
Enable the data stream by typing the following line into a shell:
Setenv SAVE sys/vumeter VU
reboot, or "
Run VU from workbench or shell or user-startup or however you want.
play anything that makes sound through AHI

For recording level, use the arg or tooltype FIRSTCHANNEL 13

/*********** Command Line Options: VU ? *****************/

L=LEFTEDGE/N,T=TOPEDGE/N,W=WIDTH/N,H=HEIGHT/N,
DEPTHGAD/S,DRAGGAD/S,CLOSEGAD/S,SIZEGAD/S,P=PUBSCREEN/K,
V=VERBOSE/S,I=INLINKNAME/K,B=BACKGROUND/K,F=FOREGROUND/K,
LEGENDS/S,VU/S,DAMPINGUP/N,DAMPINGDOWN/N,FIRSTCHANNEL/N,
LOWMETER/N,HIGHMETER/N: 

L=LEFTEDGE/N,T=TOPEDGE/N,W=WIDTH/N,H=HEIGHT/N:
These four numbers control where the window will open on your screen.
You may use the full name or the first letter for each.
Example:
VU L 100 T 100 W 50 H 300
opens VU with a medium size near your upper-left screen corner
VU LEFTEDGE 100 TOPEDGE 100 WIDTH 75 HEIGHT 300
Just the same, but a little bit wider
The defaults for these are LEFTEDGE 0 TOPEDGE 0 WIDTH 0 HEIGHT 0
which opens as small as possible in the upper left corner of your screen.

DEPTHGAD/S,DRAGGAD/S,CLOSEGAD/S,SIZEGAD/S,
These will add the gadgets named to the VU Window. VU windows can always
be closed with "break name VU" in a shell, or by sending a MIDI RESET
to the input of the VU meter

P=PUBSCREEN/K
Tells VU to open on the named Public screen. Default is "Workbench"

V=VERBOSE
If this keyword is present, VU will print out details when running. most
notably it will echo all startup options found. Default is FALSE

I=INLINKNAME
tells VU which CAMD cluster name to get audio level data from. 
Default is "VU"

B=BACKGROUND/K,F=FOREGROUND/K
These set the color of your Meter The format for both is an "ARGB Hex string".
This is an eight digit string, made up of four pairs. Often preceeded by 0x.
The first pair is..?? maybe transparency?? I don't know. I always use zero.
The next pair is Red, then the Green pair, then the Blue pair.
For each pair, the lowest number possible is 00 and the highest is FF.
Some examples:
BLACK 0x00000000
RED   0x00FF0000
GREEN 0x0000FF00
BLUE  0x000000FF
GRAY  0x00777777
WHITE 0x00FFFFFF
Obviously there are millions of possible combinations. Experiment.
Default is dark background , White foreground. (BORING!)

Legends/S
If this keyword is present, deciBel levels will be printed beside the meter,
to show exactly what your levels are. So far I have not implemented this, So 
if it's not working, I am personally to blame. Default is FALSE

VU/S
This will preset the damping to resemble a "proper" audio VU meter. You may
adjust the damping further with the next two options if you like.
Default is FALSE

DAMPINGUP/N,DAMPINGDOWN/N
These slow down the meter response, to better show average levels. Higher
damping numbers make the meter move slower in that direction. Damping 0
moves at full speed (default) maximum (slowest) damping is 255. The VU option 
presets DAMPINGUP to 240, DAMPINGDOWN to 150. These fairly approximate a real
VU meter. NOTE: If you are watching for PEAK levels, Damping is not a  good 
idea. short peaks are "hidden" by damping. Default is 0

FIRSTCHANNEL/N
The A1222 and X-1000 audio drivers encode the playback audio data into 
notes 1(Left) and 2(Right). Input levels are in notes 13(L) and 14(R)
I left note zero for Monophonic use (but who uses Mono, really??)
So to watch playback the Default 1 is correct. To watch recording levels,
set FIRSTCHANNEL to 13

LOWMETER/N,HIGHMETER/N
These let you display a smaller section of the full 0-127 meter range.

At full range, the meter displays down to about -32 dB, which is more 
sensitive than most VU meters, and likely too sensitive to hear on consumer 
grade speakers. Every point your LOWMETER raises above zero will trim 0.25 
deciBel off the bottom of the displayed range.

Reducing HIGHMETER will cause the meter to hit the top before full volume.
Which is probably a lot less useful than the LOWMETER adjustment.


/********** TOOLTYPE Options: **********************/
All the same as command line options, without the one letter shortcuts.
Right click the VU Icon, select "Information", then click on the "Icon"
tab. Enter any tooltype options you want, then SAVE.
If you're having trouble, set VERBOSE=TRUE as a tooltype to see what it's
understanding from your other tooltypes.

/************ Troubleshooting and FAQ: *******************/

If it won't work, download camdtools and use "MIDIWATCH VU" to see if there's
any data coming from the driver. If not, "Setenv SAVE sys/vumeter VU" and
reboot, then check again.

It's too small, or I don't like the colors:
Command Line options and tooltypes can make it any size and color you want.

Moving the Volume control does NOT change the displayed level.
Playback levels show what the AHI is sending to to the sound chip. If volume
is done in the sound chip, it will NOT change the displayed level. But if the
sound level is changed in AHI or in your program, you should see a difference.

The meter looks kinda like the one in TuneNet, but not quite the same:
Same levels, but TuneNet is not scaled to deciBels, a logarithmic scale
that better represents how our ears hear.

/*************** SOURCE IS INCLUDED *********************/
SOURCE CODE IS INCLUDED, Here is why:
Making it "pretty" is not my best skill.
If you want to try making it do something different, YOU SHOULD TRY!

If you haven't already, download the AmigaOS SDK from Hyperion and install it.
Copy the included source directory to somewhere on your hard drive.
Open a Shell, and CD to that directory. "CD Work:VUMeter" or something like that
then type "make". If all goes well, it will build the program fresh from the
source
code provided.

Try making simple changes first. Find an autodoc reader and read all about the
libraries that make AmigaOS work. Intuition does the GUI, Graphics does
graphics.
CAMD does MIDI stuff. DOS and EXEC are the core.

The code for this project is mostly a bunch of files ending in .h and .c
.h are header files.. Just information for the program to use.
.c are code files. functions that call each other to get the job done.

Some idea of what each file does:
vu.c is the main file. The program starts at "main()".
oca.c will open and close all the libraries and stuff. oca stands for "Open
Close All"
myargs.c reads all the command line arguments and tooltypes. oca.c calls it
midisupport.c handles all the midi, like the notes that draw the meter.
window.c opens the window, and watches for the close gadget.
storestring.c just saves text strings for convenience.
timer.c .. the timer serves to lower a damped meter if AHI stops too quickly.
project_rev.c, VU_rev.h, VU_rev.rev all help with revision control
makefile tells the compiler how to put it all together.


If you make a beautiful new meter display, please share it!


/************ About the data stream: *******************/
The driver gathers information on peak audio levels, then send messages by
CAMD to the cluster named in ENV:sys/vumeters.
Audio data is normally measured in deciBels, which is a non-linear scale.
The audio drivers convert to deciBels before sending the data, so that's already
done for you.  

This part may be a bit tricky to describe:
In a studio, a VU meter normally goes from some negative dB reading up past
Zero and up as high as +3 or even +6 deciBels. Those highest numbers are
normally in RED, while lower values are green or yellow. While that looks
cool, it's not really useful for us. Once sound has been sampled into a
digital format, there is no longer any space above Zero deciBels. We have
converted the sound into a stream of numbers, where there is a specific
maximum.. a "loudest possible" volume that the sound samples can describe.

So the values coming from our drivers are "dBFS", or "deciBel Full Scale".
The "Full Scale" or loudest possible reading is -0. Anything less is a 
negative number describing how far below "full scale" the recording is.

The MIDI messages on Channel 1, Note 1 include a "intensity" from zero(off)
1(softest possible), to 127(loudest possible). These map out as follows:

127(loudest possible) = -0 to -0.25 dBFS.
126 = -0.25 to -0.5 dBFS
125 = -0.5 to -0.75 dBFS
124 = -0.75 to -1.0 dBFS
123 = -1.0 to -1.25 dBFS
122 = -1.25 to -1.5 dBFS
121 = -1.5 to -1.75 dBFS
120 = -1.75 to -2.0 dBFS
....
1   = -31.5 to -31.75 dBFS

These are not "certified". But I think I got it right.

(value-127)/4 = dBFS, within 0.25

So the volume data is not just for display. You COULD write software
to keep track of sound levels and take action if needed.

Software can even control the output levels on the A1222 and X1000 also
by using MIDI commands. So a "smart" mixing program could be written.


/***************** Digging Deeper: **********************/
I can not teach Amiga graphics. Many others are far better than I.
If you want to see what the CAMD data stream looks like, download
"CamdTools" from OS4Depot.net, and use
MidiWatch VU
to see the data stream flying by. 

You'll have to restart the audio driver after setting ENVARC:system/vumeter
to get the data stream. But the VU display can be started and stopped anytime
without problems. You can run multiple VU meters, each with different colors,
sizes, and damping settings anytime. 

So far only the X1000 and A1222+ sound drivers support the data stream for
VU Meters. I'll likely include it in new sound programs if it's wanted.
At this time the drivers that support VU have not yet been distributed. That's
up to others.

If desired, a program could watch the meter data stream and use it to make
volume adjustments or other stuff. The data is flowing to anyone looking
for it.

The cluster name VU is user adjustable. whatever you set ENVARC:system/vumeter
to is where the driver will send the data. this will support multiple meter
streams if someone needs them at some future point.

Make beautiful music,
lylehaze()gmail.com