ChucK Manual issues
(add your own requests and contributions!)
* Missing documentation.
- units for basic things (online): for instance, what are the units for the methods of, say, Chorus? be good especially for newbies.
- LiSa and GenX doc, other than examples
- valueAt() for SndBuf is not listed on web doc
- New interfaces to the Hid device.
- Especially the differences between the KBHit and the Hid way of dealing with the keyboard turn out to lead to questions.
- General .op in UGens: On the forum Spencer noted;
All ugens have a .op parameter, which specifies how they deal with multiple inputs. the default is for the ugen to just add multiple inputs, but specifying 3 for .op will cause the ugen to multiply its inputs together. Since this happens "below the hood" so to speak its a lot better CPU-wise than multiplying in ChucK, with the added benefit of being updated every sample.
The manual only lists -1, 0 and 1 as options with he full range being being explained at the "Gain" ugen entry.
kijjaz tried applying various .op to some Ugens but multiplier, divider did not work. Trying on a Gain works well.
- The "this" keyword, similar to "me" except with regard to class-instances seems to be undocumented. Spencer explains here.
- Similarly: from some exchanges on the Forum around 14 Feb 2007: "there are a couple of references to "this" in the chuck manual. pages 31, 81. but no documentation of it's (or should i say this's) use."
Kassen replied: "I looked those up and you are right, but those references are a bit... erm.... thin (to say the least). It does make one wonder what "pure" does. The "pure" keyword gets mentioned on page 31 as well and that's the only reference to it. "const" is another mysterious word in that list." So in summary, we need some better explanations of "this", "new", "pure" and "const".
- Many of the examples referred to in the reference section as being in the /examples directory, (for example, osc.ck, pwm.ck, etc.) are no longer found there or in any subdirectories that I have been able to tell.
- VoicForm's entry refers to a list of Phonemes but doesn't include it. The following is transcribed from the source to a format that could be pasted into the manual for easy reference.--Kassen 07:57, 7 December 2007 (EST)
Allowed Phonemes. Format; number ( for .phonemeNum() ), name (for .phoneme() ), description (where available) 0 "eee" (beet) 1 "ihh" (bit) 2 "ehh" (bet) 3 "aaa" (bat) 4 "ahh" (father) 5 "aww" (bought) 6 "ohh" (bone) NOTE:: same as aww (bought) 7 "uhh" (but) 8 "uuu" (foot) 9 "ooo" (boot) 10 "rrr" (bird) 11 "lll" (lull) 12 "mmm" (mom) 13 "nnn" (nun) 14 "nng" (sang) 15 "ngg" (bong) 16 "fff" 17 "sss" 18 "thh" 19 "shh" 20 "xxx" NOTE:: Not Really Done Yet 21 "hee" (beet) 22 "hoo" (boot) 23 "hah" (father) 24 "bbb" NOTE:: Not Really Done Yet 25 "ddd" NOTE:: Not Really Done Yet 26 "jjj" NOTE:: Not Really Done Yet 27 "ggg" NOTE:: Not Really Done Yet 28 "vvv" NOTE:: Not Really Done Yet 29 "zzz" NOTE:: Not Really Done Yet 30 "thz" NOTE:: Not Really Done Yet 31 "zhh"
- "return;" as a instruction by itself can be used to abort executing a function of type "void", for example if the arguments don't make sense. "break" won't work there and "me.exit()" doesn't make sense for non-sporked functions yet the manual doesn't mention this, neither in "control structures" nor about functions. This can be quite important so I feel it deserves some attention. --Kassen 12:01, 16 February 2008 (EST)
- The manual hardly touches on Ugen calculation order, mostly that's fine because it "just works" nearly all of the time but the extra sample delay in feedback can and will affect things, for example when using tuned delays. As discussed on the list Feb29--Kassen 12:39, 2 March 2008 (EST)
- Repeat, as a flow control word is only mentioned once and never explained. To quote Ge's paper; "evaluates
the conditional as an integer only once and repeats the body that number of times."
- .last() averages where there are multiple channels (to quote Ge); " last() (of type float): get the last sample computed by the UGen. if UGen has more than one channel, the average of all components channels are returned."
- Not all MIDI functionality, particularly not "name" is documented in the manual though they are in /examples/.
* Outdated info.
- From mailing list, original text by Tazumi and Spencer, dec8;
> i have got a question about sending strings with the osc class.. > ist this possible? > The manual says that the osc object has 2 member functions > (addInt / addFloat).. > so is there a way to send (or revieve) other data types?
It seems the manual is out of date in this regard, it is in fact possible to send strings in ChucK's OSC implementation. Just use an "s" for the type specifier and addString to supply the string. getString will retrieve the string on the listener end.
* Suggested clarifications
- Add new section on this page for manual/doc errata?
- Could somebody please go into what the word "new" means in ChucK, exactly? It's currently mentioned in the manual exactly once (in that sense). It creates a new instance of a object and it's somehow syntactically similar to "!" and that's about it as far as the manual is concerned.
- The section on getting MIDI input is reportedly hard to understand.
- ChucKing a stereo soundsource to a mono one will sum the two stereo channels. This often leads to clipping. A note on this in the docs in the relevant section would be nice. Modifying the example about recording to use a gain of .5 would probably be a good idea as well, especially as this example already uses a Gain Ugen.
- I noticed that the bitwise invert '~' operator is implemented in chuck (e.g. ~1 == -2), but it isn't mentioned in the manual, at least not in the operators section. (Antimon)
* Erroneous *
(some errors remaining 220.127.116.11 version) - p. 109 under Phasor: "as a phase control. see examples/sixty.ck for an example" I can't find any example with that name - p. 103 zerox.ck is actually under "examples/basic" - p. 102 still no info on HalfRect and FullRect - p. 110 code fragment under Blit really belongs to Impulse - p. 97 "float pi -(currently disabled - use pi)" -- is it just me, or does that make no sense? - p. 88 "generaters", "These are useful for debug ChucK..." - p. 86 formatting of chuck command line is sort of garbled in my PDF viewer. It probably would really be nice to format that box with a monospaced font (chuckles/2007 10 22) - p.115 (and others in this section?) at least BandedWG claims that parameters are in the range 0.0 - 1.0, but the example bandedwg2.ck (and an error message you can get) indicate that parameters mostly range from 0 to 128)
- The VM reference claims the syntax for requesting in&out channels is "--chan" or "-c", that first one should be "--channels", "chuck --help" does report the correct syntax.(Kas.)