Enum FilePlaybackError

Namespace

VisioForge.Core.Types.MediaPlayer

Assembly

VisioForge.Core.dll

Specifies the types of errors that can occur during media file playback operations.

public enum FilePlaybackError

Fields

OK = 0

Indicates successful operation with no errors.

This value indicates that the playback operation completed successfully without any errors. All components of the media pipeline are functioning correctly, and the file is playing as expected. This is the desired state for any playback operation.

AudioError = 1

An error occurred while processing the audio stream.

This error indicates a problem specific to audio playback. Common causes include: - Missing or incompatible audio codec - Corrupted audio stream data - Audio device initialization failure - Unsupported audio format or sample rate - Audio synchronization issues

When this error occurs, video playback might continue without audio, or the entire playback might fail depending on the implementation and error handling strategy.

VideoError = 2

An error occurred while processing the video stream.

This error indicates a problem specific to video playback. Common causes include: - Missing or incompatible video codec - Corrupted video stream data - Video renderer initialization failure - Unsupported video resolution or format - Hardware acceleration issues - Insufficient GPU resources

When this error occurs, audio playback might continue without video, or the entire playback might fail. Some players may fall back to software rendering when hardware acceleration fails.

OtherStreamError = 3

An error occurred in a stream other than audio or video.

This error relates to auxiliary streams such as: - Subtitle or closed caption streams - Data streams - Metadata streams - Interactive content streams

While these errors typically don't prevent main audio/video playback, they may result in missing features like subtitles or chapter information. The severity depends on the importance of the affected stream to the user experience.

OutOfMemory = 4

The system ran out of memory during playback operations.

This critical error occurs when the system cannot allocate sufficient memory for: - Decoder buffers - Frame storage - Filter graph components - Rendering surfaces

Out of memory errors often indicate: - System resource exhaustion - Memory leaks in the application - Attempting to play files that exceed system capabilities - Too many concurrent playback operations

Recovery typically requires freeing resources and potentially restarting playback with reduced quality settings or closing other applications.

CannotConnectFilters = 5

Failed to connect filters in the media processing pipeline.

This error occurs in DirectShow or similar filter-based architectures when: - Input and output pins have incompatible media types - Required intermediate filters are missing - Filter negotiation fails - Circular connections are detected

This is often a configuration or codec issue, indicating that the system cannot build a complete processing chain from the source file to the renderer. Installing additional codecs or filters may resolve this issue.

CannotLoadSourceFilter = 6

Failed to load or initialize the source filter for the media file.

The source filter is responsible for reading and parsing the media file. This error indicates: - The file path is invalid or inaccessible - File permissions prevent reading - The source filter for this file type is not installed - The file is locked by another process - Network connectivity issues for remote files

This is typically one of the first errors that can occur, as it prevents the media pipeline from accessing the file data.

CannotRender = 7

Failed to render the media file through the playback pipeline.

Rendering failure occurs when the system cannot create a complete playback path from source to output. This comprehensive error may indicate: - Missing codecs for the file's media streams - Incompatible or missing renderer components - Display device issues - Audio device problems - Filter graph construction failures

This error often requires investigating the specific media formats in the file and ensuring all necessary components are installed and functioning.

InvalidFileFormat = 8

The file format is invalid or corrupted.

This error indicates that while the file type is recognized, the file's internal structure is invalid: - Corrupted file headers - Invalid container structure - Truncated or incomplete files - Files damaged during transfer or storage - Malformed metadata

Unlike UnknownFileType, this error means the format is recognized but the file content doesn't conform to the expected specification.

UnknownFileType = 9

The file type is not recognized or supported.

This error occurs when: - The file extension doesn't match any known format - The file signature/magic bytes are unrecognized - The container format is not supported - The file is encrypted or protected in an unknown way

This differs from InvalidFileFormat in that the system cannot even identify what type of media file this is supposed to be. Adding support for the file type would require installing appropriate format handlers.

UnsupportedStream = 10

The file contains streams that are not supported by the current configuration.

This error indicates that while the file format is recognized, it contains one or more streams using unsupported: - Codec types (e.g., HEVC when only H.264 is supported) - Codec profiles (e.g., High 10 Profile when only Main Profile is supported) - Bit depths or color spaces - Audio channel configurations - Encryption or DRM schemes

The file might be partially playable (e.g., audio works but video doesn't), or completely unplayable depending on which streams are affected.

UnknownError = 11

An unspecified error occurred during playback.

This error is used when: - The specific cause cannot be determined - Multiple errors occurred simultaneously - An unexpected exception was caught - The error doesn't fit other categories

When encountering this error, additional logging or debugging information should be consulted to determine the root cause. This is often a catch-all for unusual or system-specific failures.

Fail = 12

General playback failure without specific error details.

This is the most generic error code, indicating that playback failed but without providing specific information about the cause. It may be used when: - The underlying system doesn't provide detailed error information - Multiple cascading failures occurred - The error reporting mechanism itself failed

This error typically requires comprehensive troubleshooting, including checking system logs, verifying file integrity, and testing with different media files to isolate the issue.

Remarks

This enumeration provides detailed error codes that help identify specific issues encountered during media playback. These errors can occur at various stages of the playback pipeline, from file loading and format detection to decoding and rendering.

Understanding these error codes is crucial for: - Implementing proper error handling and recovery strategies - Providing meaningful feedback to users about playback failures - Debugging media playback issues in applications - Determining whether errors are related to file format, codec, system resources, or other factors

The error codes are hierarchical in nature, with some being more specific than others. For example, AudioError and VideoError are specific stream-related errors, while UnknownError and Fail are more general failure indicators.