@ohmykreee/dsh-remote-control 0.0.0-stage → 1.0.3

package/src/rust/src/media/vendor/qishui.rs

@@ -0,0 +1,36 @@
+//! Soda Music (汽水音乐) private adapter.
+//!
+//! The desktop client normally provides SMTC; only the title fallback lives
+//! here because the reference project does not expose a useful private API.
+
+use super::common;
+use crate::media::catalog::ParsedTitle;
+
+const SUFFIXES: &[&str] = &[" - 汽水音乐", " - Soda Music"];
+const PRODUCT_NAMES: &[&str] = &["汽水音乐", "soda music", "sodamusic"];
+
+pub fn parse_title(raw: &str) -> Option<ParsedTitle> {
+    let text = common::strip_suffixes(common::normalize_spaces(raw), SUFFIXES);
+    if common::is_generic_title(&text, PRODUCT_NAMES) {
+        return None;
+    }
+    let mut parsed = common::split_title_artist(&text, false);
+    parsed.artist = common::normalize_artist(&parsed.artist, &[(", ", " / ")]);
+    if parsed.title.is_empty() {
+        return None;
+    }
+    Some(parsed)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_soda_music_title() {
+        let parsed = parse_title("晴天 - 周杰伦 - 汽水音乐").unwrap();
+        assert_eq!(parsed.title, "晴天");
+        assert_eq!(parsed.artist, "周杰伦");
+        assert!(parse_title("汽水音乐").is_none());
+    }
+}

package/src/rust/src/media/vendor/qqmusic.rs

@@ -0,0 +1,33 @@
+//! QQ Music private window-title adapter.
+
+use super::common;
+use crate::media::catalog::ParsedTitle;
+
+const SUFFIXES: &[&str] = &[" - QQ音乐", " - QQ Music"];
+const PRODUCT_NAMES: &[&str] = &["qq音乐", "qq music"];
+
+pub fn parse_title(raw: &str) -> Option<ParsedTitle> {
+    let text = common::strip_suffixes(common::normalize_spaces(raw), SUFFIXES);
+    if common::is_generic_title(&text, PRODUCT_NAMES) {
+        return None;
+    }
+    let mut parsed = common::split_title_artist(&text, false);
+    parsed.artist = common::normalize_artist(&parsed.artist, &[("/", " / ")]);
+    if parsed.title.is_empty() {
+        return None;
+    }
+    Some(parsed)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_qq_music_title() {
+        let parsed = parse_title("晴天 - 周杰伦 - QQ音乐").unwrap();
+        assert_eq!(parsed.title, "晴天");
+        assert_eq!(parsed.artist, "周杰伦");
+        assert!(parse_title("QQ音乐").is_none());
+    }
+}

package/src/rust/src/media/vendor/spotify.rs

@@ -0,0 +1,46 @@
+//! Spotify private window-title adapter.
+//!
+//! Spotify normally provides a complete SMTC/MPRIS session. The window title
+//! fallback is only used when that session is missing; Spotify puts the artist
+//! first (`歌手 - 歌名`).
+
+use super::common;
+use crate::media::catalog::ParsedTitle;
+
+const SUFFIXES: &[&str] = &[
+    " - Spotify Premium",
+    " - Spotify Free",
+    " - Spotify",
+    " – Spotify",
+];
+const PRODUCT_NAMES: &[&str] = &[
+    "spotify",
+    "spotify free",
+    "spotify premium",
+    "spotify - free",
+];
+
+pub fn parse_title(raw: &str) -> Option<ParsedTitle> {
+    let text = common::strip_suffixes(common::normalize_spaces(raw), SUFFIXES);
+    if common::is_generic_title(&text, PRODUCT_NAMES) {
+        return None;
+    }
+    let parsed = common::split_title_artist(&text, true);
+    if parsed.title.is_empty() {
+        return None;
+    }
+    Some(parsed)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_spotify_title() {
+        let parsed = parse_title("Daft Punk - Starboy - Spotify").unwrap();
+        assert_eq!(parsed.title, "Starboy");
+        assert_eq!(parsed.artist, "Daft Punk");
+        assert!(parse_title("Spotify Free").is_none());
+    }
+}

package/src/rust/src/media/vendor/wesing.rs

@@ -0,0 +1,39 @@
+//! WeSing (全民 K 歌) private adapter.
+//!
+//! WeSing's window title is `全民K歌 - 歌名`. Progress is read from its
+//! accessibility text (`MM:SS | MM:SS`), but that lives in the platform
+//! accessibility module because it is a generic tree scan.
+
+use super::common;
+use crate::media::catalog::ParsedTitle;
+
+const PREFIX: &str = "全民K歌 - ";
+const SUFFIXES: &[&str] = &[" - 全民K歌", " - WeSing"];
+const PRODUCT_NAMES: &[&str] = &["全民k歌", "wesing"];
+
+pub fn parse_title(raw: &str) -> Option<ParsedTitle> {
+    let normalized = common::normalize_spaces(raw);
+    let stripped = common::strip_prefix_ci(&normalized, PREFIX)
+        .map(str::to_string)
+        .unwrap_or_else(|| common::strip_suffixes(normalized, SUFFIXES));
+    if common::is_generic_title(&stripped, PRODUCT_NAMES) {
+        return None;
+    }
+    let parsed = common::split_title_artist(&stripped, false);
+    if parsed.title.is_empty() {
+        return None;
+    }
+    Some(parsed)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_wesing_title() {
+        let parsed = parse_title("全民K歌 - 爱在西元前").unwrap();
+        assert_eq!(parsed.title, "爱在西元前");
+        assert!(parse_title("全民K歌").is_none());
+    }
+}

package/src/rust/src/media/vendor/youtube_music.rs

@@ -0,0 +1,49 @@
+//! YouTube Music private adapter.
+//!
+//! The desktop client and browsers usually bridge `navigator.mediaSession` to
+//! SMTC/MPRIS. This module only parses the window title fallback.
+
+use super::common;
+use crate::media::catalog::ParsedTitle;
+
+const SUFFIXES: &[&str] = &[
+    " - YouTube Music",
+    " - YouTube Music Premium",
+    " - YouTube",
+    " - YT Music",
+];
+const PRODUCT_NAMES: &[&str] = &[
+    "youtube music",
+    "youtube music premium",
+    "youtube",
+    "yt music",
+];
+
+pub fn parse_title(raw: &str) -> Option<ParsedTitle> {
+    let text = common::strip_suffixes(common::normalize_spaces(raw), SUFFIXES);
+    if common::is_generic_title(&text, PRODUCT_NAMES) {
+        return None;
+    }
+    let mut parsed = common::split_title_artist(&text, false);
+    parsed.artist = common::normalize_artist(
+        &parsed.artist,
+        &[("、", " / "), ("和", " / "), (", ", " / ")],
+    );
+    if parsed.title.is_empty() {
+        return None;
+    }
+    Some(parsed)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_youtube_music_title() {
+        let parsed = parse_title("晴天 - 周杰伦 - YouTube Music").unwrap();
+        assert_eq!(parsed.title, "晴天");
+        assert_eq!(parsed.artist, "周杰伦");
+        assert!(parse_title("YouTube Music").is_none());
+    }
+}

package/src/rust/src/media/windows/accessibility.rs

@@ -0,0 +1,85 @@
+//! Windows UI Automation tier.
+//!
+//! This is the last resort for a read-only progress display. It is used only
+//! for clients the reference project reads this way (NetEase and WeSing), and
+//! it never performs a transport action or grants seek. The scan runs on a
+//! short-lived worker thread with a timeout so a slow/hung accessibility
+//! provider cannot stall the probe.
+
+use std::ffi::c_void;
+use std::sync::mpsc;
+use std::time::Duration;
+
+use windows::Win32::Foundation::HWND;
+use windows::Win32::System::Com::{
+    CoCreateInstance, CoInitializeEx, CLSCTX_INPROC_SERVER, COINIT_MULTITHREADED,
+};
+use windows::Win32::System::Variant::{VariantInit, VARIANT, VARIANT_0_0, VT_I4};
+use windows::Win32::UI::Accessibility::{
+    CUIAutomation8, IUIAutomation, TreeScope_Descendants, UIA_ControlTypePropertyId,
+    UIA_TextControlTypeId,
+};
+
+const SCAN_TIMEOUT: Duration = Duration::from_millis(800);
+const MAX_TEXT_ELEMENTS: i32 = 5000;
+
+/// Read `MM:SS | MM:SS` progress from the window's accessibility text tree.
+pub fn progress(hwnd: isize) -> Option<(f64, f64)> {
+    if hwnd == 0 {
+        return None;
+    }
+    let (sender, receiver) = mpsc::channel();
+    std::thread::spawn(move || {
+        let _ = sender.send(unsafe { read_progress(hwnd) });
+    });
+    receiver.recv_timeout(SCAN_TIMEOUT).ok().flatten()
+}
+
+fn ensure_com() {
+    unsafe {
+        let _ = CoInitializeEx(None, COINIT_MULTITHREADED);
+    }
+}
+
+unsafe fn read_progress(hwnd: isize) -> Option<(f64, f64)> {
+    ensure_com();
+    let automation: IUIAutomation =
+        CoCreateInstance(&CUIAutomation8, None, CLSCTX_INPROC_SERVER).ok()?;
+    let window = automation
+        .ElementFromHandle(HWND(hwnd as *mut c_void))
+        .ok()?;
+    let condition_value = text_control_variant();
+    let condition = automation
+        .CreatePropertyCondition(UIA_ControlTypePropertyId, &condition_value)
+        .ok()?;
+    let elements = window.FindAll(TreeScope_Descendants, &condition).ok()?;
+    let count = elements.Length().ok()?.min(MAX_TEXT_ELEMENTS);
+    for index in 0..count {
+        let Ok(element) = elements.GetElement(index) else {
+            continue;
+        };
+        let Ok(name) = element.CurrentName() else {
+            continue;
+        };
+        if let Some(progress) = crate::media::catalog::parse_progress_text(&name.to_string()) {
+            return Some(progress);
+        }
+    }
+    None
+}
+
+fn text_control_variant() -> VARIANT {
+    // Build the inner VARIANT_0_0 separately and write it into the union; this
+    // avoids assigning through the `ManuallyDrop` field of VARIANT_0.
+    let mut inner: VARIANT_0_0 = unsafe { std::mem::zeroed() };
+    inner.vt = VT_I4;
+    inner.Anonymous.lVal = UIA_TextControlTypeId.0;
+    let mut value: VARIANT = unsafe { VariantInit() };
+    unsafe {
+        std::ptr::write(
+            std::ptr::addr_of_mut!(value.Anonymous.Anonymous),
+            std::mem::ManuallyDrop::new(inner),
+        );
+    }
+    value
+}

package/src/rust/src/media/windows/audio.rs

@@ -0,0 +1,116 @@
+//! Per-process audio activity on the default render endpoint.
+//!
+//! Several desktop players (QQ Music, KuGou, KuWo, Soda, Spotify) do not refresh
+//! their SMTC playback status unless the Windows media flyout is open. The
+//! reference project therefore uses the audio session meter/state to decide
+//! whether the client is actually playing. The probe exposes the same signal so
+//! the private tier and incomplete system sessions can correct their status.
+
+use std::collections::HashMap;
+
+use windows::core::Interface;
+use windows::Win32::Media::Audio::Endpoints::IAudioMeterInformation;
+use windows::Win32::Media::Audio::{
+    eMultimedia, eRender, AudioSessionStateActive, IAudioSessionControl2, IAudioSessionManager2,
+    IMMDeviceEnumerator, MMDeviceEnumerator,
+};
+use windows::Win32::System::Com::{
+    CoCreateInstance, CoInitializeEx, CLSCTX_ALL, COINIT_MULTITHREADED,
+};
+
+/// Aggregated state for one process.
+#[derive(Debug, Clone, Default)]
+pub struct Activity {
+    pub active: bool,
+    pub audible: bool,
+    pub exe: Option<String>,
+}
+
+impl Activity {
+    /// The client is producing sound or its audio session is active.
+    pub fn is_playing(&self) -> bool {
+        self.active || self.audible
+    }
+}
+
+fn ensure_com() {
+    static ONCE: std::sync::Once = std::sync::Once::new();
+    ONCE.call_once(|| unsafe {
+        let _ = CoInitializeEx(None, COINIT_MULTITHREADED);
+    });
+}
+
+/// Snapshot every session on the default multimedia render endpoint.
+///
+/// An empty map simply means Core Audio could not be queried; callers then keep
+/// the status reported by the system media session.
+pub fn snapshot() -> HashMap<u32, Activity> {
+    ensure_com();
+    let mut activities: HashMap<u32, Activity> = HashMap::new();
+    unsafe {
+        let enumerator: IMMDeviceEnumerator =
+            match CoCreateInstance(&MMDeviceEnumerator, None, CLSCTX_ALL) {
+                Ok(value) => value,
+                Err(_) => return activities,
+            };
+        let device = match enumerator.GetDefaultAudioEndpoint(eRender, eMultimedia) {
+            Ok(value) => value,
+            Err(_) => return activities,
+        };
+        let manager: IAudioSessionManager2 = match device.Activate(CLSCTX_ALL, None) {
+            Ok(value) => value,
+            Err(_) => return activities,
+        };
+        let sessions = match manager.GetSessionEnumerator() {
+            Ok(value) => value,
+            Err(_) => return activities,
+        };
+        let count = sessions.GetCount().unwrap_or(0);
+        for index in 0..count {
+            let Ok(control) = sessions.GetSession(index) else {
+                continue;
+            };
+            let process_id = control
+                .cast::<IAudioSessionControl2>()
+                .ok()
+                .and_then(|control| control.GetProcessId().ok())
+                .unwrap_or(0);
+            if process_id == 0 {
+                continue;
+            }
+            let peak = control
+                .cast::<IAudioMeterInformation>()
+                .ok()
+                .and_then(|meter| meter.GetPeakValue().ok())
+                .unwrap_or(0.0);
+            let state = control.GetState().ok();
+            let entry = activities.entry(process_id).or_insert_with(|| Activity {
+                exe: super::private::process_image_name(process_id),
+                ..Activity::default()
+            });
+            if state == Some(AudioSessionStateActive) {
+                entry.active = true;
+            }
+            if peak > 0.00001 {
+                entry.audible = true;
+            }
+        }
+    }
+    activities
+}
+
+/// Audio activity for one executable (case-insensitive).
+pub fn for_exe<'a>(activities: &'a HashMap<u32, Activity>, exe: &str) -> Option<&'a Activity> {
+    activities.values().find(|activity| {
+        activity
+            .exe
+            .as_deref()
+            .map(|candidate| candidate.eq_ignore_ascii_case(exe))
+            .unwrap_or(false)
+    })
+}
+
+/// Audio activity for one process id.
+pub fn for_pid<'a>(activities: &'a HashMap<u32, Activity>, pid: u32) -> Option<&'a Activity> {
+    activities.get(&pid)
+}

package/src/rust/src/media/windows/private.rs

@@ -0,0 +1,291 @@
+//! Windows private-interface tier.
+//!
+//! Many Chinese desktop players expose no usable SMTC session (or advertise one
+//! without a position). The reference project reads their top-level window
+//! titles instead, and NetEase/WeSing additionally expose `MM:SS | MM:SS`
+//! progress through the UI Automation text tree. This module implements the
+//! window-title part and Cider's `Plugins/title.txt`; the accessibility part
+//! lives in [`super::accessibility`].
+//!
+//! Window titles are read with `EnumWindows` and process image names with
+//! `QueryFullProcessImageNameW`; neither touches the network.
+
+use std::collections::HashMap;
+
+use windows::core::{BOOL, PWSTR};
+use windows::Win32::Foundation::{CloseHandle, HWND, LPARAM};
+use windows::Win32::System::Threading::{
+    OpenProcess, QueryFullProcessImageNameW, PROCESS_NAME_WIN32, PROCESS_QUERY_LIMITED_INFORMATION,
+};
+use windows::Win32::UI::WindowsAndMessaging::{
+    EnumWindows, GetWindowTextLengthW, GetWindowTextW, GetWindowThreadProcessId, IsWindowVisible,
+};
+
+use super::super::catalog::{self, PrivateKind, Profile, Tier};
+use super::super::{Media, ReadOptions};
+use super::audio::{self, Activity};
+use crate::util;
+
+/// A visible or hidden top-level window belonging to a desktop process.
+#[derive(Debug, Clone)]
+pub struct WindowInfo {
+    pub hwnd: isize,
+    pub pid: u32,
+    pub exe: String,
+    pub title: String,
+    pub visible: bool,
+}
+
+pub fn enumerate_windows() -> Vec<WindowInfo> {
+    let mut windows: Vec<WindowInfo> = Vec::new();
+    unsafe {
+        let _ = EnumWindows(
+            Some(enum_window),
+            LPARAM(&mut windows as *mut Vec<WindowInfo> as isize),
+        );
+    }
+    windows
+}
+
+unsafe extern "system" fn enum_window(hwnd: HWND, lparam: LPARAM) -> BOOL {
+    let windows = &mut *(lparam.0 as *mut Vec<WindowInfo>);
+    let mut pid = 0u32;
+    GetWindowThreadProcessId(hwnd, Some(&mut pid));
+    if pid == 0 {
+        return BOOL(1);
+    }
+    let length = GetWindowTextLengthW(hwnd);
+    if length <= 0 {
+        return BOOL(1);
+    }
+    let mut buffer = vec![0u16; length as usize + 1];
+    let copied = GetWindowTextW(hwnd, &mut buffer);
+    if copied <= 0 {
+        return BOOL(1);
+    }
+    let title = String::from_utf16_lossy(&buffer[..copied as usize]);
+    if title.trim().is_empty() {
+        return BOOL(1);
+    }
+    windows.push(WindowInfo {
+        hwnd: hwnd.0 as isize,
+        pid,
+        exe: process_image_name(pid).unwrap_or_default(),
+        title,
+        visible: IsWindowVisible(hwnd).as_bool(),
+    });
+    BOOL(1)
+}
+
+/// Full executable name (no directory) for a process id.
+pub fn process_image_name(pid: u32) -> Option<String> {
+    unsafe {
+        let handle = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, false, pid).ok()?;
+        let mut buffer = [0u16; 1024];
+        let mut size = buffer.len() as u32;
+        let result = QueryFullProcessImageNameW(
+            handle,
+            PROCESS_NAME_WIN32,
+            PWSTR(buffer.as_mut_ptr()),
+            &mut size,
+        );
+        let _ = CloseHandle(handle);
+        result.ok()?;
+        let path = String::from_utf16_lossy(&buffer[..size as usize]);
+        path.rsplit(['\\', '/'])
+            .next()
+            .map(str::to_string)
+            .filter(|name| !name.is_empty())
+    }
+}
+
+/// Build a private-tier media payload for `profile`, if a matching window (or
+/// Cider title file) exists.
+pub fn read(
+    profile: &'static Profile,
+    windows: &[WindowInfo],
+    activities: &HashMap<u32, Activity>,
+    smtc: Option<&Media>,
+    options: &ReadOptions,
+) -> Option<Media> {
+    if matches!(profile.private, PrivateKind::None) {
+        return None;
+    }
+    let window = best_window(profile, windows)?;
+    let (parsed, detail) = match profile.private {
+        PrivateKind::CiderTitleFile => match crate::media::vendor::apple_music::cider_title() {
+            Some(parsed) => (parsed, "cider-title"),
+            None => (profile.parse_title(&window.title)?, "window-title"),
+        },
+        _ => (profile.parse_title(&window.title)?, "window-title"),
+    };
+
+    let app_id = if window.exe.is_empty() {
+        profile.app_id.to_string()
+    } else {
+        window.exe.clone()
+    };
+    let mut media = Media::new(app_id);
+    media.provider = Tier::Private.as_str().to_string();
+    media.provider_detail = detail.to_string();
+    media.title = parsed.title;
+    media.artist = parsed.artist;
+    media.playback_status = playback_status(profile, windows, activities, &window.exe, smtc);
+
+    // The private tier is read-only. If a partial SMTC session exists we can
+    // still use its transport controls, but never its seek grant.
+    if let Some(smtc) = smtc {
+        media.album = smtc.album.clone();
+        media.album_artist = smtc.album_artist.clone();
+        media.track_number = smtc.track_number;
+        media.auto_repeat_mode = smtc.auto_repeat_mode.clone();
+        media.shuffle_active = smtc.shuffle_active;
+        media.can_play_pause = smtc.can_play_pause;
+        media.can_next = smtc.can_next;
+        media.can_previous = smtc.can_previous;
+        if options.thumbnail {
+            media.thumbnail = smtc.thumbnail.clone();
+            media.thumbnail_type = smtc.thumbnail_type.clone();
+        }
+    } else {
+        media.can_play_pause = false;
+        media.can_next = false;
+        media.can_previous = false;
+    }
+    media.can_seek = catalog::seek_allowed(Tier::Private, false, false);
+    media.last_updated_at = util::now_ms();
+
+    // Accessibility is the last resort for a read-only progress display. It is
+    // never allowed to grant seek (see `catalog::seek_allowed`). NetEase defers
+    // this to `vendor::netease::resolve` so CDP can take precedence.
+    if profile.smtc_policy != catalog::SmtcPolicy::MetadataOnly {
+        attach_progress(profile, windows, &mut media);
+    }
+    Some(media)
+}
+
+/// Find `MM:SS | MM:SS` progress for a profile's window. The caller decides
+/// whether accessibility is appropriate; this only performs the scan.
+pub fn progress_for_profile(profile: &Profile, windows: &[WindowInfo]) -> Option<(f64, f64)> {
+    if !profile.accessibility {
+        return None;
+    }
+    let window = best_window(profile, windows)?;
+    super::accessibility::progress(window.hwnd)
+}
+
+/// Attach UI Automation progress to a media item.
+pub fn attach_progress(profile: &Profile, windows: &[WindowInfo], media: &mut Media) -> bool {
+    let Some((position, total)) = progress_for_profile(profile, windows) else {
+        return false;
+    };
+    if total <= 0.0 {
+        return false;
+    }
+    media.position = position;
+    media.start_time = 0.0;
+    media.end_time = total;
+    media.min_seek_time = 0.0;
+    media.max_seek_time = total;
+    media.last_updated_at = util::now_ms();
+    if media.provider_detail.contains("smtc") {
+        media.provider_detail = "smtc+uia".to_string();
+    } else {
+        media.provider_detail = format!("{}+uia", media.provider_detail);
+    }
+    true
+}
+
+/// Audio activity for a profile, using the first matching window process.
+pub fn profile_activity<'a>(
+    profile: &Profile,
+    windows: &[WindowInfo],
+    activities: &'a HashMap<u32, Activity>,
+) -> Option<&'a Activity> {
+    if let Some(activity) = windows
+        .iter()
+        .filter(|window| {
+            catalog::profile_for_process(&window.exe)
+                .map(|candidate| candidate.app == profile.app)
+                .unwrap_or(false)
+        })
+        .find_map(|window| {
+            audio::for_exe(activities, &window.exe)
+                .or_else(|| audio::for_pid(activities, window.pid))
+        })
+    {
+        return Some(activity);
+    }
+    // Some clients play audio through a helper process (KuWo's `KwService`)
+    // that owns no window. Match the audio session by its process profile.
+    activities.values().find(|activity| {
+        activity
+            .exe
+            .as_deref()
+            .and_then(catalog::profile_for_process)
+            .map(|candidate| candidate.app == profile.app)
+            .unwrap_or(false)
+    })
+}
+
+fn playback_status(
+    profile: &Profile,
+    windows: &[WindowInfo],
+    activities: &HashMap<u32, Activity>,
+    exe: &str,
+    smtc: Option<&Media>,
+) -> String {
+    if let Some(activity) = audio::for_exe(activities, exe) {
+        return if activity.is_playing() {
+            "Playing".to_string()
+        } else {
+            "Paused".to_string()
+        };
+    }
+    if let Some(activity) = profile_activity(profile, windows, activities) {
+        return if activity.is_playing() {
+            "Playing".to_string()
+        } else {
+            "Paused".to_string()
+        };
+    }
+    smtc.map(|media| media.playback_status.clone())
+        .unwrap_or_else(|| "Paused".to_string())
+}
+
+fn best_window<'a>(profile: &Profile, windows: &'a [WindowInfo]) -> Option<&'a WindowInfo> {
+    let mut candidates: Vec<&WindowInfo> = windows
+        .iter()
+        .filter(|window| {
+            catalog::profile_for_process(&window.exe)
+                .map(|candidate| candidate.app == profile.app)
+                .unwrap_or(false)
+        })
+        .collect();
+    // Keep enumeration (z-order) order inside each visibility class.
+    candidates.sort_by_key(|window| !window.visible);
+
+    for window in &candidates {
+        if profile.parse_title(&window.title).is_some() {
+            return Some(window);
+        }
+    }
+    if matches!(profile.private, PrivateKind::CiderTitleFile)
+        && crate::media::vendor::apple_music::cider_title().is_some()
+        && !candidates.is_empty()
+    {
+        return candidates.first().copied();
+    }
+    candidates.first().copied()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn process_image_name_of_current_process_exists() {
+        let name = process_image_name(std::process::id()).unwrap_or_default();
+        assert!(name.to_lowercase().ends_with(".exe"), "{name}");
+    }
+}