[sc-dev] change default cue buffer size patch

[Lucas Samaruga <samarugalucas@xxxxxxxxx>]

Hi

Maybe this change could be useful, maybe not. With many files at the same time a buffer size of 32768 produces random glitches and the recommender values in DiskIn is at least 65536.

Of corse I made a mistake spacing the help file before changing it...

Best

Lucas

From d7efb3e537b6e807616b4aec2a9380544fa67eb7 Mon Sep 17 00:00:00 2001
From: = <=>
Date: Mon, 18 Nov 2013 15:47:27 -0300
Subject: [PATCH 1/2] spacing Buffer.schelp

---
 HelpSource/Classes/Buffer.schelp |   24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/HelpSource/Classes/Buffer.schelp b/HelpSource/Classes/Buffer.schelp
index ad27fd5..9b065b7 100644
--- a/HelpSource/Classes/Buffer.schelp
+++ b/HelpSource/Classes/Buffer.schelp
@@ -2,7 +2,7 @@ class:: Buffer
 summary:: Client-side representation of a buffer on a server
 categories:: Server>Abstractions
 
-description::
+DESCRIPTION::
 
 A buffer is most often used to hold sampled audio, such as a soundfile loaded into memory, but can be used to hold other types of data as well. It is a globally available array of floating-point numbers on the server. The Buffer class encapsulates a number of common tasks, OSC messages, and capabilities related to server-side buffers – see the examples lower down this document for many examples of using Buffers for sound playback and recording.
 
@@ -10,6 +10,7 @@ Buffers are commonly used with link::Classes/PlayBuf::, link::Classes/RecordBuf:
 
 Buffer objects should not be created or modified within a link::Classes/SynthDef::. If this is needed, see link::Classes/LocalBuf::.
 
+
 subsection:: Buffer Numbers and Allocation
 
 Although the number of buffers on a server is set at the time it is booted, memory must still be allocated within the server app before they can hold values. (At boot time all buffers have a size of 0.)
@@ -18,6 +19,7 @@ link::Classes/Server::-side buffers are identified by number, starting from 0. W
 
 Normally you should not need to supply a buffer number. You should only do so if you are sure you know what you are doing. Similarly, in normal use you should not need to access the buffer number, since instances of Buffer can be used directly as link::Classes/UGen:: inputs or link::Classes/Synth:: args.
 
+
 subsection:: Multichannel Buffers
 
 Multichannel buffers interleave their data. Thus the actual number of available values when requesting or setting values by index using methods such as code::set, setn, get, getn::, etc., is equal to code::numFrames * numChannels::.
@@ -26,6 +28,7 @@ In a two channel buffer for instance, index 0 will be the first value of the fir
 
 In some cases it is simpler to use multiple single channel buffers instead of a single multichannel one.
 
+
 subsection:: Completion Messages and Action Functions
 
 Many buffer operations (such as reading and writing files) are asynchronous, meaning that they will take an arbitrary amount of time to complete. Asynchronous commands are passed to a background thread on the server so as not to steal CPU time from the audio synthesis thread.
@@ -40,15 +43,18 @@ Action functions are therefore inherently more flexible than completion messages
 With Buffer methods that take a completion message, it is also possible to pass in a function that returns an OSC message. As in action functions this will be passed the Buffer as an argument.
 It is important to understand however that this function will be evaluated after the Buffer object has been created (so that its bufnum and other details are accessible), but before the corresponding message is sent to the server.
 
+
 subsection:: Bundling
 
 Many of the methods below have two versions: a regular one which sends its corresponding message to the server immediately, and one which returns the message in an link::Classes/Array:: so that it can be added to a bundle.
 It is also possible to capture the messages generated by the regular methods using Server's automated bundling capabilities.
 See link::Classes/Server:: and link::Guides/Bundled-Messages:: for more details.
 
-classmethods::
+
+CLASSMETHODS::
 private:: initClass, initServerCache, clearServerCaches
 
+
 subsection:: Creation with Immediate Memory Allocation
 
 method:: alloc
@@ -118,7 +124,6 @@ argument:: action
 A Function to be evaluated once the file has been read and this Buffer's instance variables have been updated. The function will be passed this Buffer as an argument.
 argument:: bufnum
 An explicitly specified buffer number. Generally this is not needed.
-
 discussion::
 N.B. You cannot rely on the buffer's instance variables being instantly updated, as there is a small amount of latency involved. action will be evaluated upon receipt of the reply to the query, so use this in cases where access to instance variables is needed.
 code::
@@ -276,7 +281,6 @@ argument:: numChannels
 The number of channels that the buffer should have. Note that buffers interleave multichannel data. You are responsible for providing an interleaved collection if needed. Multi-dimensional arrays will not work.
 argument:: action
 A Function to be evaluated once the file has been read and this Buffer's instance variables have been updated. The function will be passed this Buffer as an argument.
-
 discussion::
 This is accomplished through writing the collection to a SoundFile and loading it from there. For this reason this method will only work with a server on your local machine. For a remote server use code::sendCollection::, below. The file is automatically deleted after loading. This allows for larger collections than setn, below, and is in general the safest way to get a large collection into a buffer. The sample rate of the buffer will be the sample rate of the server on which it is created.
 code::
@@ -353,7 +357,9 @@ b = Buffer.loadDialog(s, action: { arg buffer;
 x.free; b.free;
 ::
 
+
 subsection:: Creation without Immediate Memory Allocation
+
 method:: new
 Create and return a new Buffer object, without immediately allocating the corresponding memory on the server. This combined with 'message' methods can be flexible with bundles.
 argument:: server
@@ -376,6 +382,7 @@ c.query;
 b.free; c.free;
 ::
 
+
 subsection:: Cached Buffers
 
 To assist with automatic updates of buffer information (see code::updateInfo:: and code::read::), buffer objects are cached in a collection associated with the link::Classes/Server:: object hosting the buffers.
@@ -401,7 +408,8 @@ method:: cachedBuffersDo
 Iterate over all cached buffers. The iteration is not in any order, but will touch all buffers.
 
 
-InstanceMethods::
+INSTANCEMETHODS::
+
 
 subsection:: Variables
 
@@ -491,6 +499,7 @@ x = { PlayBuf.ar(1, b, BufRateScale.kr(b), loop: 1) * 0.5 }.play;
 x.free; b.free;
 ::
 
+
 subsection:: Other methods
 
 method:: read, readMsg
@@ -510,7 +519,6 @@ argument:: action
 A Function to be evaluated once the file has been read and this Buffer's instance variables have been updated. The function will be passed this Buffer as an argument.
 argument:: completionMessage
 A valid OSC message or a Function which will return one. A Function will be passed this Buffer as an argument when evaluated.
-
 discussion::
 Note that if the number of frames in the file is greater than the number of frames in the buffer, it will be truncated. Note that readMsg will not auto-update instance variables. Call updateInfo in order to do this.
 
@@ -619,7 +627,6 @@ argument:: startFrame
 The index of the frame at which to start loading the collection. The default is 0, which is the start of the buffer.
 argument:: action
 A Function to be evaluated once the file has been read and this Buffer's instance variables have been updated. The function will be passed this Buffer as an argument.
-
 discussion::
 This allows for larger collections than setn, above, and is in general the safest way to get a large collection into a buffer. The sample rate of the buffer will be the sample rate of the server on which it was created.
 The number of channels and frames will have been determined when the buffer was allocated. You are responsible for making sure that the size of collection is not greater than numFrames, and for interleaving any data if needed.
@@ -835,7 +842,9 @@ b.updateInfo({|buf| buf.numFrames.postln; }); // now it's right
 b.free;
 ::
 
+
 subsection:: Buffer Fill Commands
+
 These correspond to the various b_gen OSC Commands, which fill the buffer with values for use. See link::Reference/Server-Command-Reference:: for more details.
 
 method:: gen, genMsg
@@ -935,4 +944,3 @@ x = {
 )
 x.free; b.free;
 ::
-
-- 
1.7.9.5

From 833e0a6b22c94bb5386d18bdee17c850de440a60 Mon Sep 17 00:00:00 2001
From: = <=>
Date: Mon, 18 Nov 2013 16:45:36 -0300
Subject: [PATCH 2/2] cueSoundFile: change default buffer size to 65536

---
 HelpSource/Classes/Buffer.schelp        |   12 +++++-------
 HelpSource/Classes/VDiskIn.schelp       |    2 +-
 SCClassLibrary/Common/Control/Buffer.sc |    8 ++++----
 3 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/HelpSource/Classes/Buffer.schelp b/HelpSource/Classes/Buffer.schelp
index 9b065b7..a351781 100644
--- a/HelpSource/Classes/Buffer.schelp
+++ b/HelpSource/Classes/Buffer.schelp
@@ -238,7 +238,7 @@ b.free;
 ::
 
 method:: cueSoundFile
-Allocate a buffer and preload a soundfile for streaming in using link::Classes/DiskIn::.
+Allocate a buffer and preload a soundfile for streaming in using link::Classes/DiskIn::. See also link::#-cueSoundFile::.
 argument:: server
 The server on which to allocate the buffer.
 argument:: path
@@ -248,7 +248,7 @@ The frame of the soundfile that DiskIn will start playing at.
 argument:: numChannels
 The number of channels in the soundfile.
 argument:: bufferSize
-This must be a multiple of  (2 * the server's block size). 32768 is the default and is suitable for most cases.
+This must be a power of two number of frames greater than or equal to twice the server's block size. 65536 is the default value and the safest for most cases.
 argument:: completionMessage
 A valid OSC message or a Function which will return one. A Function will be passed this Buffer as an argument when evaluated.
 discussion::
@@ -513,8 +513,7 @@ The number of frames to read. The default is -1, which will read the whole file.
 argument:: bufStartFrame
 The index of the frame in the buffer at which to start reading. The default is 0, which is the beginning of the buffer.
 argument:: leaveOpen
-A boolean indicating whether or not the Buffer should be left 'open'. For use with DiskIn you will want this to be true, as the buffer will be used for streaming the soundfile in from disk. (For this the buffer must have been allocated with a multiple of (2 * synth block size).
-A common number is 32768 frames. cueSoundFile below, provides a simpler way of doing this.) The default is false which is the correct value for all other cases.
+A boolean indicating whether or not the Buffer should be left 'open'. For use with DiskIn you will want this to be true, as the buffer will be used for streaming the soundfile in from disk. (For this the buffer must have been allocated with a power of two number of frames greater than or equal to twice the server's block size. The safest number is 65536 for most cases. link::#-cueSoundFile:: below, provides a simpler way of doing this.) The default is false which is the correct value for all other cases.
 argument:: action
 A Function to be evaluated once the file has been read and this Buffer's instance variables have been updated. The function will be passed this Buffer as an argument.
 argument:: completionMessage
@@ -533,8 +532,7 @@ The number of frames to read. The default is -1, which will read the whole file.
 argument:: bufStartFrame
 The index of the frame in the buffer at which to start reading. The default is 0, which is the beginning of the buffer.
 argument:: leaveOpen
-A boolean indicating whether or not the Buffer should be left 'open'. For use with DiskIn you will want this to be true, as the buffer will be used for streaming the soundfile in from disk. (For this the buffer must have been allocated with a multiple of (2 * synth block size).
-A common number is 32768 frames. cueSoundFile below, provides a simpler way of doing this.) The default is false which is the correct value for all other cases.
+A boolean indicating whether or not the Buffer should be left 'open'. For use with link::Classes/DiskIn:: you will want this to be true, as the buffer will be used for streaming the soundfile in from disk. (For this the buffer must have been allocated with a a power of two number of frames greater than or equal to twice the server's block size. The safest number is 65536 for most cases. link::#-cueSoundFile:: below, provides a simpler way of doing this.) The default is false which is the correct value for all other cases.
 argument:: channels
 An Array of channels to be read from the soundfile. Indices start from zero. These will be read in the order provided. The number of channels requested must match this Buffer's numChannels.
 argument:: action
@@ -543,7 +541,7 @@ argument:: completionMessage
 A valid OSC message or a Function which will return one. A Function will be passed this Buffer as an argument when evaluated.
 
 method:: cueSoundFile, cueSoundFileMsg
-A convenience method to cue a soundfile into the buffer for use with a link::Classes/DiskIn::. The buffer must have been allocated with a multiple of (2 * the server's block size) frames.  A common size is 32768 frames.
+A convenience method to cue a soundfile into the buffer for use with a link::Classes/DiskIn::. The buffer must have been allocated with a power of two number of frames greater than or equal to twice the server's block size. Depending on the hardware and the amount of r/w operations a higher buffer size is needed to avoid gliches. See also link::#*cueSoundFile::.
 argument:: path
 A String representing the path of the soundfile to be read.
 argument:: startFrame
diff --git a/HelpSource/Classes/VDiskIn.schelp b/HelpSource/Classes/VDiskIn.schelp
index a638ffa..7a52d16 100644
--- a/HelpSource/Classes/VDiskIn.schelp
+++ b/HelpSource/Classes/VDiskIn.schelp
@@ -20,7 +20,7 @@ argument:: rate
 controls the rate of playback. Values below 4 are probably fine, but the higher the value, the more disk activity there is, and the more likelihood there will be a problem.
 
 warning::
-the rate does have a practical limit. The following must be true: rate < Buffer's size / ( 2 * s.options.blockSize) e.g with typical default values, this wil be 32768 / (2 * 64) = 256.
+the rate does have a practical limit. The following must be true: rate < Buffer's size / ( 2 * s.options.blockSize) e.g with typical default values, this wil be 65536 / (2 * 64) = 512.
 ::
 
 If the rate is too high, the UGen will not execute, posting a warning.
diff --git a/SCClassLibrary/Common/Control/Buffer.sc b/SCClassLibrary/Common/Control/Buffer.sc
index d4e23b1..1fc55c2 100644
--- a/SCClassLibrary/Common/Control/Buffer.sc
+++ b/SCClassLibrary/Common/Control/Buffer.sc
@@ -154,11 +154,11 @@ Buffer {
 	}
 
 	// preload a buffer for use with DiskIn
-	*cueSoundFile { arg server,path,startFrame = 0,numChannels= 2,
-			 bufferSize=32768,completionMessage;
+	*cueSoundFile { arg server, path, startFrame = 0, numChannels = 2,
+					bufferSize = 65536, completionMessage;
 		^this.alloc(server,bufferSize,numChannels,{ arg buffer;
-						buffer.readMsg(path,startFrame,bufferSize,0,true,completionMessage)
-					}).cache;
+			buffer.readMsg(path,startFrame,bufferSize,0,true,completionMessage)
+		}).cache;
 	}
 
 	cueSoundFile { arg path,startFrame,completionMessage;
-- 
1.7.9.5