{"record":{"id":"d5838c99c9c6b920","repo":"stride3d/stride","slug":"failed-to-create-celt-custom-mode","errorCode":null,"errorMessage":"Failed to create Celt custom mode.","messagePattern":"Failed to create Celt custom mode\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Audio/Native/Celt.AVFoundation.cs","lineNumber":47,"sourceCode":"        private const int OPUS_GET_LOOKAHEAD_REQUEST = 4027;\n\n        public int SampleRate { get; set; }\n        public int BufferSize { get; set; }\n        public int Channels { get; set; }\n\n        private IntPtr mode;\n        private IntPtr decoder;\n        private IntPtr encoder;\n\n        public Celt(int sampleRate, int bufferSize, int channels, bool decoderOnly)\n        {\n            SampleRate = sampleRate;\n            BufferSize = bufferSize;\n            Channels = channels;\n\n            mode = opus_custom_mode_create(sampleRate, bufferSize, IntPtr.Zero);\n            if (mode == IntPtr.Zero)\n                throw new Exception(\"Failed to create Celt custom mode.\");\n\n            decoder = opus_custom_decoder_create(mode, channels, IntPtr.Zero);\n            if (decoder == IntPtr.Zero)\n                throw new Exception(\"Failed to create Celt decoder.\");\n\n            if (!decoderOnly)\n            {\n                encoder = opus_custom_encoder_create(mode, channels, IntPtr.Zero);\n                if (encoder == IntPtr.Zero)\n                    throw new Exception(\"Failed to create Celt encoder.\");\n            }\n        }\n\n        public void Dispose()\n        {\n            if (encoder != IntPtr.Zero) { opus_custom_encoder_destroy(encoder); encoder = IntPtr.Zero; }\n            if (decoder != IntPtr.Zero) { opus_custom_decoder_destroy(decoder); decoder = IntPtr.Zero; }\n            if (mode != IntPtr.Zero) { opus_custom_mode_destroy(mode); mode = IntPtr.Zero; }","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Audio/Native/Celt.AVFoundation.cs#L29-L65","documentation":"Thrown from the Celt constructor when the native call opus_custom_mode_create returns NULL, meaning the codec library could not create a custom mode for the requested sampleRate/bufferSize combination. Celt custom modes only accept specific sample rates and frame sizes, so invalid parameters make native initialization impossible.","triggerScenarios":"Constructing Celt with a sample rate outside the codec's supported range or a bufferSize that is not a valid frame size for that rate (e.g. unusual sample rates on iOS/AVFoundation path).","commonSituations":"Configuring audio on iOS/macOS with hardware-reported sample rates that don't match the expected Celt constants; typos in sample rate constants; memory exhaustion in native allocation (rare).","solutions":["Use a supported sample rate for Celt custom mode (e.g. 48000 Hz) with its matching frame buffer size.","Query the audio hardware sample rate and resample or select a compatible Celt mode instead of passing the raw value.","Verify the bundled native Celt/Opus library is present and compatible with the platform.","Check for native memory pressure if parameters are known-valid."],"exampleFix":"// before\nvar celt = new Celt(deviceSampleRate, 256, channels, decoderOnly:false);\n// after\nconst int celtSampleRate = 48000;\nvar celt = new Celt(celtSampleRate, 256, channels, decoderOnly:false); // device input resampled to celtSampleRate","handlingStrategy":"try-catch","validationCode":"public static bool IsCeltCompatibleRate(int sampleRate) =>\n    sampleRate == 48000 || sampleRate == 24000 || sampleRate == 16000 || sampleRate == 12000 || sampleRate == 8000;","typeGuard":null,"tryCatchPattern":"try\n{\n    var celt = new Celt(sampleRate, bufferSize, channels, decoderOnly);\n}\ncatch (Exception ex) when (ex.Message.Contains(\"Failed to create Celt custom mode\"))\n{\n    logger.Error($\"Unsupported Celt mode for rate={sampleRate} size={bufferSize}; falling back.\");\n    celt = new Celt(48000, bufferSize, channels, decoderOnly);\n}","preventionTips":["Use only codec-supported sample rates; resample hardware input to a supported rate.","Keep bufferSize consistent with the encoder used to produce assets.","Verify native opus/celt libraries ship with every target platform build.","Test audio codec initialization on each platform in CI (including iOS/macOS simulators)."],"tags":["audio","celt","native","codec","initialization"],"backgroundTag":"module-init-failed","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}