Tinko

Tinko is an offline music player for iOS and macOS with a port/recreation of Spicy Lyrics - A Spicetify Extension, designed to achieve visual parity with Spicy Lyrics' rendering. Built using SwiftUI and AVFoundation.

The iOS and macOS version uses an app-local library workflow: import songs or whole folders, copy audio and .ttml files into the app's storage, auto-pair by basename, and render synchronized lyrics during playback.

Warning

This is a work in progress. The app is not yet complete and may have bugs.

---

Key Features

High-Fidelity Lyrics Rendering

• Sub-Pixel Text Positioning: Uses Compose's TextMeasurer for exact glyph calculation.
• Duet-Aware Layout: Identifies primary (v1) and guest (v2) artists from TTML metadata.
• Intelligent Alignment: Primary artists are justified to the left, and guest artists to the right, with multi-line blocks correctly right-aligned for balance.

Physics-Driven Motion

• Analytic Spring Engine: Replaces traditional Euler/Verlet integration with a mathematically exact (closed-form) solution for damped harmonic oscillators. This ensures that a target set 500ms in the future is reached exactly, with zero energy drift.
• Critical Damping (ζ = 1.0): Used for all auto-scroll centering to provide the fastest non-oscillatory return possible.
• Under-damped Springs: Used for word-bouncing and interlude-dot expansions to provide a lively, bouncy character.

Synchronized Animations

• Held Word Bounce: Syllables with a duration >= 1000ms automatically receive a bouncy scale and Y-offset animation, highlighting them letter-by-letter.
• Instrumental Break Dots: Injected automatically for gaps >= 3000ms, featuring a "breathe" pulse effect synced with the song's timing.
• Seamless Seek: Clicking any lyric line instantly re-bases the physics spring to the current visual position, ensuring no "snap-back" jumps when transitioning from manual scrolling back to auto-focus.

---

iOS & macOS (Mac Catalyst) Features

The iOS/Mac build supports an app-local library workflow:

• Mac Catalyst Support: Run the app natively on macOS with the "Optimize Interface for Mac" idiom (using crisp 1.0 pixel scaling and responsive layout adjustments).
• Spacebar Playback Control: Toggle play/pause globally using the Spacebar keyboard shortcut (safely ignored when typing in the search bar).
• Premium Styling: Uses Apple's native .glassEffect(in:) for Liquid Glass styling (iOS 26.0+) with high-fidelity glassmorphic fallbacks on earlier versions.
• Custom Icon: Uses a custom spicylyrics.icon asset bundle (managed under ios/TinkoiOS/Resources/) to support customized IconComposer designs natively.

iOS/Mac Import Behavior

• Import Song: Copies one audio file into the app-local library and attempts to auto-import a sibling .ttml file.
• Import Folder: Recursively scans a selected directory for supported audio and .ttml files.
• Attach Lyrics: Manually pairs a selected .ttml lyrics file with the currently loaded track.
• Persistent Storage: Imported tracks and per-song offset sync adjustments persist across launches (stored in the app's Application Support folder).

Manual Builds

GitHub Actions includes a manual workflow at .github/workflows/build-mobile.yml.

• platform: build ios
• ios_export: export an unsigned device ipa for sideload tools or an unsigned simulator-app

The workflow generates the Xcode project from ios/project.yml using XcodeGen on the macOS runner, then builds either:

• an unsigned device .ipa suitable for local resigning/sideloading tools such as Sideloadly
• an unsigned iOS Simulator .app zip

License

This project is licensed under the AGPL-3.0 License, inherited from the Spicy Lyrics project. See the LICENSE file for the full text.

---

Made by Bobjoerules with the help of Antigravity's available models. Based on Spicy Lyrics - A Spicetify Extension