1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
//! # Tracing / Logging
//!
//! Audex supports structured tracing via the `tracing` crate when
//! the `"tracing"` feature is enabled. All trace points compile away
//! to nothing when the feature is disabled, ensuring zero overhead
//! for users who do not need observability.
//!
//! ## Setup
//!
//! ```toml
//! [dependencies]
//! audex = { version = "0.1", features = ["tracing"] }
//! tracing-subscriber = "0.3"
//! ```
//!
//! ```rust,ignore
//! // Initialize a subscriber in your application:
//! tracing_subscriber::fmt()
//! .with_env_filter("audex=debug")
//! .init();
//!
//! // Now all audex operations emit structured events:
//! let file = audex::File::load("song.mp3")?;
//! // Output:
//! // DEBUG audex::file: format detected format="MP3"
//! // DEBUG audex::mp3: MPEG stream info parsed bitrate=320 sample_rate=44100 channels=2
//! // INFO audex::file: file loaded successfully format="MP3" tags_present=true
//! ```
//!
//! ## Verbosity Levels
//!
//! | Filter | What you see |
//! |-----------------|-------------------------------------------------|
//! | `audex=error` | Only unrecoverable failures |
//! | `audex=warn` | Recoverable issues + errors |
//! | `audex=info` | Operation lifecycle + warnings + errors |
//! | `audex=debug` | Parsed summaries + all above |
//! | `audex=trace` | Per-item parsing details (very verbose) |
//!
//! ## Level Semantics
//!
//! - **ERROR** — Unrecoverable failures that will be returned as `Err`.
//! Example: `error_event!("FLAC header magic not found")`
//!
//! - **WARN** — Recoverable issues, degraded results, or skipped data.
//! Example: `warn_event!("unknown ID3v2 frame skipped: {}", frame_id)`
//!
//! - **INFO** — High-level operation lifecycle (start/end of load/save).
//! Example: `info_event!("file loaded successfully")`
//!
//! - **DEBUG** — Format detection results, parsed component summaries.
//! Example: `debug_event!(tag_count = 15, "Vorbis Comment parsed")`
//!
//! - **TRACE** — Per-item/per-byte parsing details (very verbose).
//! Example: `trace_event!(frame_id = "TIT2", size = 42, "parsing frame")`
//!
//! ## Recommended Subscriber Configuration
//!
//! ```rust,ignore
//! // In your application:
//! tracing_subscriber::fmt()
//! .with_env_filter("audex=debug") // or "audex=trace" for full detail
//! .init();
//! ```
// ---------------------------------------------------------------------------
// Conditional event macros — forward to `tracing` when the feature is enabled,
// compile to nothing when it is disabled.
// ---------------------------------------------------------------------------
/// Emit a TRACE-level event (per-item parsing details, very verbose).
/// Emit a DEBUG-level event (parsed summaries, format detection results).
/// Emit an INFO-level event (operation lifecycle — load/save start and end).
/// Emit a WARN-level event (recoverable issues, skipped data).
/// Emit an ERROR-level event (unrecoverable failures).