load_bounded()

std::shared_ptr< Kakshya::DynamicSoundStream > MayaFlux::IO::SoundFileReader::load_bounded	(	const std::string &	filepath,
		uint64_t	max_frames = 0,
		bool	truncate = false
	)

Load an audio file into a size-bounded DynamicSoundStream.

Opens the file, reads up to max_frames frames into a fully resident DynamicSoundStream with auto-resize disabled, then closes the file. No DataProcessor is configured on the result; that is the caller's responsibility (see IOManager::configure_audio_processor).

Parameters

filepath	Path to the audio file.
max_frames	Upper bound on frame count. Defaults to 5 seconds at the target sample rate.
truncate	If true, silently truncate files that exceed max_frames with an MF_WARN. If false, return nullptr on excess.

Returns

Populated DynamicSoundStream, or nullptr on failure.

Definition at line 289 of file SoundFileReader.cpp.

{
    if (!can_read(filepath)) {
        set_error("load_bounded: unsupported file: " + filepath);
        return nullptr;
    }
 
    if (!open(filepath, FileReadOptions::EXTRACT_METADATA)) {
        set_error("load_bounded: open failed: " + get_last_error());
        return nullptr;
    }
 
    std::shared_ptr<AudioStreamContext> audio;
    {
        std::shared_lock lock(m_context_mutex);
        audio = m_audio;
    }
 
    if (!audio || !audio->is_valid()) {
        set_error("load_bounded: no valid audio stream");
        close();
        return nullptr;
    }
 
    const uint64_t effective_rate = m_target_sample_rate > 0
        ? m_target_sample_rate
        : audio->sample_rate;
 
    if (max_frames == 0)
        max_frames = effective_rate * 5;
 
    const bool over_limit = audio->total_frames > max_frames;
 
    if (over_limit && !truncate) {
        set_error(std::format(
            "load_bounded: file has {} frames, exceeds limit of {}",
            audio->total_frames, max_frames));
        close();
        return nullptr;
    }
 
    if (over_limit) {
        MF_WARN(Journal::Component::IO, Journal::Context::FileIO,
            "load_bounded: {} has {} frames, truncating to {}",
            filepath, audio->total_frames, max_frames);
    }
 
    const uint64_t frames_to_load = over_limit ? max_frames : audio->total_frames;
    const bool planar = (m_audio_options & AudioReadOptions::DEINTERLEAVE) != AudioReadOptions::NONE;
 
    auto stream = std::make_shared<Kakshya::DynamicSoundStream>(
        effective_rate,
        static_cast<uint32_t>(audio->channels));
 
    stream->get_structure().organization = planar
        ? Kakshya::OrganizationStrategy::PLANAR
        : Kakshya::OrganizationStrategy::INTERLEAVED;
 
    stream->set_auto_resize(false);
    stream->ensure_capacity(frames_to_load);
 
    auto data = over_limit
        ? read_frames(frames_to_load, 0)
        : read_all();
 
    close();
 
    if (data.empty()) {
        set_error("load_bounded: read returned no data");
        return nullptr;
    }
 
    stream->set_all_data(data);
 
    return stream;
}

References can_read(), close(), MayaFlux::IO::DEINTERLEAVE, MayaFlux::IO::EXTRACT_METADATA, MayaFlux::Journal::FileIO, get_last_error(), MayaFlux::Kakshya::INTERLEAVED, MayaFlux::Journal::IO, m_audio, m_audio_options, m_context_mutex, m_target_sample_rate, MF_WARN, MayaFlux::IO::NONE, open(), MayaFlux::Kakshya::PLANAR, read_all(), read_frames(), and set_error().

Here is the call graph for this function: