Weird behaviour of note_columns[].volume_value and .panning_value


While developing my clip composing language I stumbled over this weird behaviour:
When the volume or panning column contains an effect >= “G” with the amount parameter being
F, the Lua API returns 255.

Here is a complete listing of the mapping between volume_value (in decimal notations) and
volume_string of the same column:

volume_value AF = 2575  
volume_value BF = 2831  
volume_value CF = 3087  
volume_value DF = 3343  
volume_value EF = 3599  
volume_value FE = 3854  
volume_value GF = 255  
volume_value HF = 255  
volume_value IF = 255  
volume_value JF = 255  
volume_value KF = 255  
volume_value LF = 255  
volume_value MF = 255  
volume_value NF = 255  
volume_value OF = 255  
volume_value PF = 255  
volume_value QF = 255  
volume_value RF = 255  
volume_value SF = 255  
volume_value TF = 255  
volume_value UF = 255  
volume_value VF = 255  
volume_value WF = 255  
volume_value XF = 255  
volume_value YF = 255  
volume_value ZF = 255  

Is there something I am missing? says, that for example “QF” should delay a note by 15 ticks.
So I would expect every other value than 255 (0xFF) here.

Does this mean, that I should use the volume_string and panning_string values exclusively to access the volume/panning column values?
Unless I’m doing something wrong, I guess this is a possible workaround, but I will have to encode my numeric values myself from the volume_value.
However, assigning values like 0x1A0F (= QF) to the volume_value works, also reading it back works in this case.

Just know that for both panning and volume, the values must lie between 0 and 80 (128). Maybe 81 can be input, but won’t have any effect. So you can check if .volume_value <= 128, then do something with the volume value, otherwise probably just let it be since it’ll be a mini-effect-command, or use .volume_string.

This is also mentioned in the docs[].tracks[].lines[].note_columns[].volume_value  
 -> [number, 0-127, 255==Empty when column value is <= 0x80 or is 0xFF,  
 i.e. is used to specify volume]  
 [number, 0-65535 in the form 0x0000xxyy where  
 xx=effect char 1 and yy=effect char 2,  
 when column value is > 0x80, i.e. is used to specify an effect]  

So the best way to go around it is probably first check if it’s regular volume (ie <= 0x80), if not, use volume_string, which also gives a clear, unambiguous representation of the content (e.g. “…” is no value entered, assume full or last used volume/velocity). In my opinion the implementation is quite alright.[].tracks[].lines[].note_columns[].volume_string  
 -> [string, '00' - 'ZF' or '..']  

If the implementation was alright, then it would not return 0xFF in volume_value when there is a
valid effect command in the volume column, for example “QF”, which has a very valid and documented
(as you quoted) representation as number (that would be 0x1A0F).

Q0-QE return valid values, only QF returns an invalid value.
So the F range doesn’t seem properly covered for the letter commands.[1].tracks[1].lines[1].note_columns[1].volume_value=6671 does indeed correctly set it to QF

Meanwhile, using the string_value for checking the actual value is your best option.

Indeed, I was/am not sure if it was “F” only.

Right, that would be a workaround. But I guess I will live with the bug until
the fix, so I don’t have to optimize away the workaround once it’s fixed. (I don’t
use the volume/panning FX so often, and with regard to my tool writing that value
is much more common, which actually works).

In this case you are lucky there is a solution.
I had a similar problem regarding string_value vs _value between 2.6 and 2.7.
Quite comfortable i never had to change that code.
Back with 2.8.0, i had the less fortunate problem that the first LFO parameter of the the instrument envelope LFO values were falsely double assigned to an API call for the second LFO so there was no way to get around that.

And some documented API calls weren’t even implemented.

This is indeed a bug in the API. Fixed this now for the next release.

Thanks for reporting.