{"record":{"id":"fa3cd71c6ae47b23","repo":"MonoGame/MonoGame","slug":"the-loopstart-cannot-be-greater-than-the-total-num","errorCode":null,"errorMessage":"The loopStart cannot be greater than the total number of samples.","messagePattern":"The loopStart cannot be greater than the total number of samples\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MonoGame.Framework/Audio/SoundEffect.cs","lineNumber":189,"sourceCode":"                throw new ArgumentException(\"Ensure that the buffer length is non-zero.\", \"buffer\");\r\n\r\n            var blockAlign = (int)channels * 2;\r\n            if (count <= 0)\r\n                throw new ArgumentException(\"Ensure that the count is greater than zero.\", \"count\");\r\n            if ((count % blockAlign) != 0)\r\n                throw new ArgumentException(\"Ensure that the count meets the block alignment requirements for the number of channels.\", \"count\");\r\n\r\n            if (offset < 0)\r\n                throw new ArgumentException(\"The offset cannot be negative.\", \"offset\");\r\n            if (((ulong)count + (ulong)offset) > (ulong)buffer.Length)\r\n                throw new ArgumentException(\"Ensure that the offset+count region lines within the buffer.\", \"offset\");\r\n\r\n            var totalSamples = count / blockAlign;\r\n\r\n            if (loopStart < 0)\r\n                throw new ArgumentException(\"The loopStart cannot be negative.\", \"loopStart\");\r\n            if (loopStart > totalSamples)\r\n                throw new ArgumentException(\"The loopStart cannot be greater than the total number of samples.\", \"loopStart\");\r\n\r\n            if (loopLength == 0)\r\n                loopLength = totalSamples - loopStart;\r\n\r\n            if (loopLength < 0)\r\n                throw new ArgumentException(\"The loopLength cannot be negative.\", \"loopLength\");\r\n            if (((ulong)loopStart + (ulong)loopLength) > (ulong)totalSamples)\r\n                throw new ArgumentException(\"Ensure that the loopStart+loopLength region lies within the sample range.\", \"loopLength\");\r\n\r\n            _duration = GetSampleDuration(count, sampleRate, channels);\r\n\r\n            PlatformInitializePcm(buffer, offset, count, 16, sampleRate, channels, loopStart, loopLength);\r\n        }\r\n\r\n        #endregion\r\n\r\n        #region Finalizer\r\n\r","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/MonoGame/MonoGame/blob/1d71bbd0ff4071a03caa583aa3bc56b85924a819/MonoGame.Framework/Audio/SoundEffect.cs#L171-L207","documentation":"Thrown as ArgumentException (paramName 'loopStart') from the public SoundEffect constructor when loopStart > totalSamples (totalSamples = count / blockAlign). A loop start beyond the sample range is unreachable; the loop region must begin within the actual audio. The check uses '>' (not '>=') so loopStart == totalSamples is allowed only when loopLength is 0/empty, which is then defaulted.","triggerScenarios":"Passing a loopStart larger than the number of available samples; computing loop points from a different sample-rate than the source (resample mismatch); forwarding loop markers from a longer source after trimming the buffer.","commonSituations":"Loop points derived from the original untrimmed audio applied to a trimmed clip; resampling the buffer without rescaling loop points; loop points read in bytes but passed as samples (or vice versa); stale loop metadata after editing the PCM.","solutions":["Recompute loopStart in samples against the actual buffer: ensure 0 <= loopStart <= totalSamples.","When trimming or resampling, rescale loopStart by the same ratio.","Clamp loopStart to totalSamples (or pass 0 to disable looping).","Pass loopStart=0, loopLength=0 to let MonoGame default to a full-buffer loop if you only want whole-sample looping."],"exampleFix":"// before\nvar sfx = new SoundEffect(trimmedBuf, 0, trimmedBuf.Length, rate, ch, origLoopStart, loopLen);\n// origLoopStart refers to the pre-trim source -> throws\n\n// after\nint totalSamples = trimmedBuf.Length / ((int)ch * 2);\nint loopStart = Math.Min(origLoopStart - trimHeadSamples, totalSamples);\nloopStart = Math.Max(0, loopStart);\nvar sfx = new SoundEffect(trimmedBuf, 0, trimmedBuf.Length, rate, ch, loopStart, loopLen);","handlingStrategy":"validation","validationCode":"int totalSamples = count / ((int)ch * 2);\nint loopStart = Math.Clamp(requestedLoopStart, 0, totalSamples);\nvar sfx = new SoundEffect(buffer, offset, count, rate, ch, loopStart, loopLength);","typeGuard":"static bool LoopStartInRange(int loopStart, int totalSamples)\n    => loopStart >= 0 && loopStart <= totalSamples;","tryCatchPattern":"try { return new SoundEffect(buf, off, count, rate, ch, ls, ll); }\ncatch (ArgumentException ex) when (ex.ParamName == \"loopStart\" && ex.Message.Contains(\"greater than the total\"))\n{ int t = count/((int)ch*2); return new SoundEffect(buf, off, count, rate, ch, Math.Min(ls,t), ll); }","preventionTips":["Recompute loopStart in samples against the actual buffer after trimming/resampling.","Rescale loop points by the same ratio as any resample/trim operation.","Pass loopStart=0, loopLength=0 for whole-buffer looping without manual math."],"tags":["audio","argument-validation","monogame","looping"],"backgroundTag":null,"analyzedSha":"1d71bbd0ff4071a03caa583aa3bc56b85924a819","analyzedAt":"2026-08-13T17:10:33.625Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}