{"record":{"id":"2fb93cb16d7d4330","repo":"stride3d/stride","slug":"failed-to-compile-a-sound-asset-ffmpeg-was-not-found","errorCode":null,"errorMessage":"Failed to compile a sound asset, ffmpeg was not found.","messagePattern":"Failed to compile a sound asset, ffmpeg was not found\\.","errorType":"exception","errorClass":"AssetException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Assets/Media/SoundAssetCompiler.cs","lineNumber":44,"sourceCode":"        {\n            var asset = (SoundAsset)assetItem.Asset;\n            result.BuildSteps = new AssetBuildStep(assetItem);\n            result.BuildSteps.Add(new DecodeSoundFileCommand(targetUrlInStorage, asset, assetItem.Package));\n        }\n\n        protected class DecodeSoundFileCommand : AssetCommand<SoundAsset>\n        {\n            public DecodeSoundFileCommand(string url, SoundAsset parameters, IAssetFinder assetFinder)\n                : base(url, parameters, assetFinder)\n            {\n                Version = 5;\n            }\n\n            /// <inheritdoc />\n            protected override async Task<ResultStatus> DoCommandOverride(ICommandContext commandContext)\n            {\n                // Get path to ffmpeg\n                var ffmpeg = ToolLocator.LocateTool(\"ffmpeg\", ensureExecutable: true)?.ToOSPath() ?? throw new AssetException(\"Failed to compile a sound asset, ffmpeg was not found.\");\n\n                // Get absolute path of asset source on disk\n                var assetDirectory = Parameters.Source.GetParent();\n                var assetSource = UPath.Combine(assetDirectory, Parameters.Source);\n\n                // Execute ffmpeg to convert source to PCM and then encode with Celt\n                var tempFile = Path.GetTempFileName();\n                try\n                {\n                    var channels = Parameters.Spatialized ? 1 : 2;\n                    var commandLine = \"  -hide_banner -loglevel error\" + // hide most log output\n                                      $\" -i \\\"{assetSource.ToOSPath()}\\\"\" + // input file\n                                      $\" -f f32le -acodec pcm_f32le -ac {channels} -ar {Parameters.SampleRate}\" + // codec\n                                      $\" -map 0:{Parameters.Index}\" + // stream index\n                                      $\" -y \\\"{tempFile}\\\"\"; // output file (always overwrite)\n                    var ret = await ShellHelper.RunProcessAndGetOutputAsync(ffmpeg, commandLine, commandContext.Logger);\n                    if (ret != 0 || commandContext.Logger.HasErrors)\n                    {","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Assets/Media/SoundAssetCompiler.cs#L26-L62","documentation":"SoundAssetCompiler requires the external ffmpeg tool to convert audio sources before Celt encoding. ToolLocator.LocateTool(\"ffmpeg\") returned null (ffmpeg not on PATH, not bundled, or not executable), so compilation aborts with an AssetException before any conversion is attempted.","triggerScenarios":"DoCommandOverride runs on a sound asset and ToolLocator cannot locate an ffmpeg executable (returns null).","commonSituations":"ffmpeg not installed on the build machine/CI agent, ffmpeg present but not on PATH, downloaded ffmpeg lacking execute permission (Linux/macOS), a stripped-down Stride install without bundled tools.","solutions":["Install ffmpeg and ensure it is on the system PATH (or set the tool location Stride uses)","On Linux/macOS run chmod +x on the ffmpeg binary if it exists but isn't executable","Verify with 'ffmpeg -version' in a shell from the same environment the build runs in","On CI, add an ffmpeg install step to the pipeline before the build"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before building sound assets, verify ffmpeg is locatable\nif (ToolLocator.LocateTool(\"ffmpeg\", ensureExecutable: true) is null)\n    throw new InvalidOperationException(\"Install ffmpeg and add it to PATH before building audio assets.\");","typeGuard":"static bool FfmpegAvailable() => ToolLocator.LocateTool(\"ffmpeg\", ensureExecutable: true) != null;","tryCatchPattern":"try\n{\n    await CompileSoundAsync(asset);\n}\ncatch (AssetException ex) when (ex.Message.Contains(\"ffmpeg was not found\"))\n{\n    logger.Error(\"Install ffmpeg (https://ffmpeg.org) and ensure it is on PATH, then rebuild.\");\n}","preventionTips":["Install ffmpeg on every machine/CI agent that builds audio assets","Verify with 'ffmpeg -version' before running builds","Ensure downloaded binaries are marked executable on Linux/macOS","Bake ffmpeg into CI docker images"],"tags":["audio","ffmpeg","build-pipeline","external-tool"],"backgroundTag":"command-not-found","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"}