core: Add Scout-compatible FLM telemetry system

Add an opt-in telemetry backend that records frame, render, input,
network, and memory metrics in Adobe Scout's FLM format, with support
for live streaming over TCP in addition to writing to a file.

- New `core/src/telemetry.rs` module with span/counter recording and
  AMF3-based FLM serialization
- Desktop CLI gains a `--telemetry` flag to opt in and configure output
- Player and context wiring to record frame/render/input/network spans
  and counters, plus bitmap decompression timing (`rend.buildbits`)
- Adds a Python-based FLM reader/decoder and end-to-end tests under
  tests/tests/telemetry, plus usage documentation

Author: gpeacock

.gitignore

@@ -14,6 +14,9 @@ RECOVER_*.fla
 # Jetbrains tools (CLion, IntelliJ, etc)
 /.idea
 
+# VS Code settings
+/.vscode
+
 # Mac junk
 .DS_Store
 

core/src/backend/audio.rs

@@ -194,6 +194,11 @@ pub trait AudioBackend: Any {
     fn is_sound_playing(&self, instance: SoundInstanceHandle) -> bool {
         self.get_sound_position(instance).is_some()
     }
+
+    /// Returns the total compressed memory used by all registered sounds, in kilobytes.
+    fn total_sound_memory_kb(&self) -> i32 {
+        0
+    }
 }
 
 /// Information about a sound provided to `NullAudioBackend`.
@@ -314,6 +319,10 @@ impl AudioBackend for NullAudioBackend {
         None
     }
 
+    fn total_sound_memory_kb(&self) -> i32 {
+        (self.sounds.values().map(|s| s.size as usize).sum::<usize>() / 1024) as i32
+    }
+
     fn volume(&self) -> f32 {
         self.volume
     }

core/src/backend/audio/mixer.rs

@@ -687,6 +687,10 @@ impl AudioMixer {
         self.sounds.get(sound).map(|s| s.data.len() as u32)
     }
 
+    pub fn total_sound_memory_kb(&self) -> i32 {
+        (self.sounds.values().map(|s| s.data.len()).sum::<usize>() / 1024) as i32
+    }
+
     pub fn get_sound_format(&self, sound: SoundHandle) -> Option<&swf::SoundFormat> {
         self.sounds.get(sound).map(|s| &s.format)
     }
@@ -1167,5 +1171,10 @@ macro_rules! impl_audio_mixer_backend {
         fn get_sample_history(&self) -> [[f32; 2]; 1024] {
             self.$mixer.get_sample_history()
         }
+
+        #[inline]
+        fn total_sound_memory_kb(&self) -> i32 {
+            self.$mixer.total_sound_memory_kb()
+        }
     };
 }

core/src/bitmap/bitmap_data.rs

@@ -8,6 +8,17 @@ use ruffle_render::backend::RenderBackend;
 use ruffle_render::bitmap::{
     Bitmap, BitmapFormat, BitmapHandle, PixelRegion, PixelSnapping, SyncHandle,
 };
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+static BITMAP_MEMORY_BYTES: AtomicUsize = AtomicUsize::new(0);
+
+/// Returns the current total bitmap memory in kilobytes,
+/// including both CPU-side BitmapData pixels and GPU-registered character bitmaps.
+pub fn bitmap_memory_kb() -> i32 {
+    let cpu_bytes = BITMAP_MEMORY_BYTES.load(Ordering::Relaxed);
+    let gpu_bytes = crate::character::registered_bitmap_memory_kb() as usize * 1024;
+    ((cpu_bytes + gpu_bytes) / 1024) as i32
+}
 use ruffle_wstr::WStr;
 use std::cell::Ref;
 use std::fmt::Debug;
@@ -417,6 +428,7 @@ pub enum DirtyState {
 }
 
 mod wrapper {
+    use super::BITMAP_MEMORY_BYTES;
     use crate::avm2::object::BitmapDataObject;
     use crate::context::RenderContext;
     use crate::display_object::DisplayObjectWeak;
@@ -427,6 +439,7 @@ mod wrapper {
     use ruffle_render::bitmap::{BitmapHandle, PixelRegion, PixelSnapping};
     use ruffle_render::commands::CommandHandler;
     use std::cell::Ref;
+    use std::sync::atomic::Ordering;
 
     use super::{BitmapRawData, DirtyState, copy_pixels_to_bitmapdata};
 
@@ -494,9 +507,11 @@ mod wrapper {
         /// Clones the underlying data, producing a new `BitmapData`
         /// that has no GPU texture or associated display objects
         pub fn clone_data(&self, renderer: &mut dyn RenderBackend) -> BitmapRawData<'gc> {
-            // Sync from the GPU to CPU, since our new BitmapData starts out
-            // with no GPU texture
             let data = self.sync(renderer).borrow();
+            BITMAP_MEMORY_BYTES.fetch_add(
+                BitmapRawData::pixel_byte_size(data.width, data.height),
+                Ordering::Relaxed,
+            );
             BitmapRawData {
                 pixels: data.pixels.clone(),
                 width: data.width,
@@ -506,7 +521,6 @@ mod wrapper {
                 bitmap_handle: None,
                 avm2_object: None,
                 display_objects: vec![],
-                // We have no GPU texture, so there's no need to mark as dirty
                 dirty_state: DirtyState::Clean,
                 #[cfg(feature = "egui")]
                 egui_texture: Default::default(),
@@ -728,7 +742,12 @@ impl std::fmt::Debug for BitmapRawData<'_> {
 }
 
 impl<'gc> BitmapRawData<'gc> {
+    fn pixel_byte_size(width: u32, height: u32) -> usize {
+        width as usize * height as usize * std::mem::size_of::<Color>()
+    }
+
     pub fn new(width: u32, height: u32, transparency: bool, fill_color: u32) -> Self {
+        BITMAP_MEMORY_BYTES.fetch_add(Self::pixel_byte_size(width, height), Ordering::Relaxed);
         Self {
             pixels: vec![
                 Color::bgra_u32(fill_color).to_premultiplied_alpha(transparency);
@@ -753,6 +772,7 @@ impl<'gc> BitmapRawData<'gc> {
         transparency: bool,
         pixels: Vec<Color>,
     ) -> Self {
+        BITMAP_MEMORY_BYTES.fetch_add(Self::pixel_byte_size(width, height), Ordering::Relaxed);
         Self {
             pixels,
             width,
@@ -773,11 +793,14 @@ impl<'gc> BitmapRawData<'gc> {
     }
 
     pub fn dispose(&mut self) {
+        BITMAP_MEMORY_BYTES.fetch_sub(
+            Self::pixel_byte_size(self.width, self.height),
+            Ordering::Relaxed,
+        );
         self.width = 0;
         self.height = 0;
-        self.pixels = Vec::new(); // free the CPU pixel buffer
+        self.pixels = Vec::new();
         self.bitmap_handle = None;
-        // There's no longer a handle to update
         self.dirty_state = DirtyState::Clean;
         self.disposed = true;
     }

core/src/character.rs

@@ -1,4 +1,5 @@
 use std::cell::OnceCell;
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
 
 use crate::backend::audio::SoundHandle;
 use crate::binary_data::BinaryData;
@@ -14,6 +15,22 @@ use ruffle_render::bitmap::{Bitmap as RenderBitmap, BitmapHandle, BitmapSize};
 use ruffle_render::error::Error as RenderError;
 use swf::DefineBitsLossless;
 
+static REGISTERED_BITMAP_BYTES: AtomicUsize = AtomicUsize::new(0);
+
+/// Accumulates microseconds spent decompressing image assets (JPEG / lossless).
+/// Drained each frame into a telemetry span.
+static DECOMPRESS_MICROS: AtomicU64 = AtomicU64::new(0);
+
+/// Returns the total GPU-registered bitmap memory (SWF character bitmaps) in kilobytes.
+pub fn registered_bitmap_memory_kb() -> i32 {
+    (REGISTERED_BITMAP_BYTES.load(Ordering::Relaxed) / 1024) as i32
+}
+
+/// Drains and returns the accumulated image-decompression time in microseconds since the last call.
+pub fn drain_decompress_micros() -> u64 {
+    DECOMPRESS_MICROS.swap(0, Ordering::Relaxed)
+}
+
 #[derive(Copy, Clone, Collect, Debug)]
 #[collect(no_drop)]
 pub enum Character<'gc> {
@@ -73,9 +90,13 @@ impl<'gc> BitmapCharacter<'gc> {
         if let Some(handle) = self.handle.get() {
             return Ok(handle.clone());
         }
+        let t0 = std::time::Instant::now();
         let decoded = self.compressed.decode()?;
+        DECOMPRESS_MICROS.fetch_add(t0.elapsed().as_micros() as u64, Ordering::Relaxed);
+        let bitmap_bytes = decoded.width() as usize * decoded.height() as usize * 4;
         let new_handle = backend.register_bitmap(decoded)?;
         // FIXME - do we ever want to release this handle, to avoid taking up GPU memory?
+        REGISTERED_BITMAP_BYTES.fetch_add(bitmap_bytes, Ordering::Relaxed);
         self.handle.set(new_handle.clone()).unwrap();
         Ok(new_handle)
     }

core/src/context.rs

@@ -37,6 +37,7 @@ use crate::string::{AvmString, StringContext};
 use crate::stub::StubCollection;
 use crate::system_properties::SystemProperties;
 use crate::tag_utils::{SwfMovie, SwfSlice};
+use crate::telemetry::TelemetryMetrics;
 use crate::timer::Timers;
 use crate::vminterface::Instantiator;
 use async_channel::Sender;
@@ -73,6 +74,9 @@ pub struct UpdateContext<'gc> {
     /// A collection of stubs encountered during this movie.
     pub stub_tracker: &'gc mut StubCollection,
 
+    /// Telemetry metrics collector for the current SWF session.
+    pub telemetry: &'gc mut TelemetryMetrics,
+
     /// The library containing character definitions for this SWF.
     /// Used to instantiate a `DisplayObject` of a given ID.
     pub library: &'gc mut Library<'gc>,
@@ -355,6 +359,22 @@ impl<'gc> UpdateContext<'gc> {
             self.frame_rate,
         );
 
+        // Initialize telemetry with metadata from the newly-loaded SWF.
+        let fps: f64 = movie.frame_rate().into();
+        let size_kb = ((movie.compressed_len() + 512) / 1024).max(1) as i32;
+        self.telemetry.set_swf_name(movie.url());
+        self.telemetry.set_swf_rate(fps);
+        self.telemetry.set_swf_size(size_kb);
+        self.telemetry.set_swf_dimensions(
+            movie.width().to_pixels() as i32,
+            movie.height().to_pixels() as i32,
+        );
+        self.telemetry
+            .set_swf_vm(if movie.is_action_script_3() { 2 } else { 1 });
+        self.telemetry.add_network_loadmovie(movie.url());
+        self.telemetry.add_network_received(size_kb);
+        self.telemetry.set_swf_start(0);
+
         *self.root_swf = Arc::new(movie);
         *self.instance_counter = 0;
 

core/src/lib.rs

@@ -58,6 +58,7 @@ pub mod debug_ui;
 pub mod external;
 pub mod i18n;
 pub mod stub;
+pub mod telemetry;
 
 pub use context_menu::ContextMenuItem;
 pub use events::PlayerEvent;