Active & Working

Added #

Performance Enhancements

• Ultra-Fast Audio URL Fetching: Introduced getAudioUrlFast() method that retrieves audio URLs in under 1 second (90%+ faster than standard method)

  • Optimized for scenarios where video ID is already known
  • Single-shot extraction with minimal overhead
  • No retry logic for maximum speed

• Intelligent Search Caching: Implemented client-side result caching with automatic expiration

  • Cache duration: 5 minutes (configurable)
  • Automatic cache size management (max 50 entries)
  • 98%+ faster for repeated queries
  • Cache management utilities: clearCache(), clearCacheForQuery(), getCacheStats()

• Batch Audio URL Fetching: New getAudioUrlsFastBatch() method for parallel processing

  • Fetch multiple audio URLs simultaneously
  • Intelligent batching to prevent rate limiting
  • Up to 5 URLs retrieved in ~2 seconds

• Enhanced Stream Progress Tracking: Added optional progress callbacks to streaming methods

  • Real-time progress monitoring for long-running streams
  • Timeout warning system for slow searches
  • Better user feedback during data fetching

Improved #

Search Performance

• Reduced Initial Latency: First search result now appears in 1-3 seconds (down from 5-10 seconds)

  • 60-80% improvement in time-to-first-result
  • Optimized Python generator creation with 5-second timeout
  • Streamlined Kotlin-Python bridge communication

• Faster Result Processing:

  • Reduced per-item timeout from 20s to 8s
  • Eliminated unnecessary batching for immediate result delivery
  • Pre-allocated thread pools to avoid cold-start delays
  • Higher thread priority for search operations

• Python Engine Optimizations:

  • Single-attempt search with fail-fast strategy
  • Parallel audio URL extraction using ThreadPoolExecutor
  • Quick thumbnail extraction from existing data (no HQ fetch delay)
  • Album art caching to prevent redundant network calls
  • Reduced retry attempts from 3 to 2 for faster failure recovery

Resource Management

• Executor Reuse: Thread pool executors are now cached and reused

  • Eliminates thread creation overhead
  • Consistent performance across multiple requests
  • Proper cleanup on disposal

• Connection Pooling: Implemented persistent HTTP connection pool

  • Reduced connection establishment time
  • Better resource utilization
  • Improved throughput for consecutive requests

Fixed #

• Generator creation timeout issues that caused 5-10 second delays
• Memory leaks in long-running search sessions
• Race conditions in parallel audio URL fetching
• Inefficient thumbnail quality resolution
• Unnecessary HQ album art fetching for standard quality requests

Performance Metrics #

Operation	Before (v3.3.x)	After (v3.4.0)	Improvement
First search result	5-10s	1-3s	70-80% faster
Cached search	N/A	<100ms	Instant
Audio URL (fast method)	5-10s	<1s	90%+ faster
Audio URL (standard)	5-10s	2-3s	50-60% faster
Stream initialization	5-10s	1-2s	80% faster
Batch audio URLs (5 items)	25-50s	~2s	92% faster

Migration Notes #

New Methods

// Ultra-fast audio URL fetching (requires video ID)
final result = await api.getAudioUrlFast(videoId: 'dQw4w9WgXcQ');

// Batch fetch multiple audio URLs
final urls = await api.getAudioUrlsFastBatch(
  videoIds: ['video1', 'video2', 'video3'],
);

// Search with caching (enabled by default)
final results = await api.searchMusic(
  query: 'Blinding Lights',
  useCache: true, // Can be disabled if needed
);

// Stream with progress tracking
await for (final result in api.streamSearchResults(
  query: 'The Weeknd',
  onProgress: (processed, total) {
    print('Progress: $processed/$total');
  },
)) {
  // Handle result
}

// Cache management
api.clearCache(); // Clear all cache
api.clearCacheForQuery('specific query'); // Clear specific query
final stats = api.getCacheStats(); // Get cache statistics

Breaking Changes

• None. All changes are backward compatible.

Recommended Updates

• Consider using getAudioUrlFast() instead of getAudioUrlFlexible() when video ID is known
• Enable caching for frequently searched queries to improve user experience
• Use batch methods when fetching multiple audio URLs simultaneously

Developer Notes #

Python Backend

• Added get_audio_url_fast() method to YTMusicSearcher class
• Implemented _process_search_batch_parallel() for concurrent processing
• Added _album_art_cache dictionary for thumbnail URL caching
• Optimized get_music_details() generator for immediate yielding

Kotlin Layer

• Implemented handleGetAudioUrlFast() with 3-second maximum timeout
• Optimized SearchStreamHandler with reduced timeouts and parallel processing
• Added prewarmSearchEngine() for cold-start mitigation
• Cached executor pools at class level for reuse

Dart Interface

• Added caching layer with _searchCache and _cacheTimestamps maps
• Implemented cache management utilities
• Enhanced progress tracking for streaming methods
• Added batch processing support for audio URLs

Known Limitations #

• Cache is in-memory only and cleared on app restart
• Fast audio URL method doesn't support quality selection (uses best available)
• Batch audio URL fetching has a rate limit safety delay of 100ms between batches
• Cache size limited to 50 entries to prevent excessive memory usage

Active & Working

Updated #

• Updated the internal python plugin versions with : ("yt-dlp==2025.12.08", "ytmusicapi==1.11.4")

EOL

Added #

• Introduced streamRadio method to fetch dynamic radio playlists.
  This method provides real-time, frequently updated radio streams based on evolving algorithms.

Fixed #

• Updated internal yt-dlp dependency from 2025.06.30 to 2025.07.21.
  Previous versions (<=2025.06.30) are no longer supported by this plugin and may result in audio extraction failures.

⚠️ Note: Plugins using older yt-dlp versions will fail due to breaking changes in upstream audio extraction logic. Ensure your dependencies reflect the updated version for compatibility.

[3.3.5]

NOT Working

Added #

• Added a method getAudioUrlFlexible which gives a single result for audiourl based on either Title/Artist or videoId

Fixed #

• Minor fixes to get_audio_url added code if the selected quality wasn't found the engine will autoselect the best available.

[3.3.4]

Active & Working

Fixed #

• Minor fixes to handleInitialization, get_audio_url.

[3.3.3]

Active & Working

Fixed #

• Minor Patches to handleInitialization, handlePythonInitialization, handleDispose
• Fixed the results mixup issues by properly improving cancellations

[3.3.2]

Active & Working

Fixed #

• Ensured robust per-search cancellation by tracking and checking the latest active search ID for each stream type.

• Added a final guard in both Kotlin and Python to prevent yielding or emitting results from any previous/cancelled stream.

• Eliminated edge-case race conditions that could allow items from a canceled query to appear in a new search stream.

• Unified cancellation handling across all stream handlers to guarantee only current query results reach the client.[3.3.1]

Added #

• Finalized generator-safe StreamHandlers for:

• SearchStreamHandler

• RelatedSongsStreamHandler

• ArtistSongsStreamHandler

• SongDetailsStreamHandler

• These handlers now integrate global stream cancellation rules, ensuring only the latest active stream is allowed to emit items.

• Active generator identity verification using isLatestOfType(...) and has(...) in SearchManager to prevent late emissions from stale generators.

• Stream-safe coroutine helpers that fully honor onCancel() and avoid generator.close errors during rapid query changes.

Fixed #

• 🛡️ 1% race condition that allowed a stale item ("my strange addiction") from a previous generator after switching to a new stream (e.g. "Dance Monkey"). This was eliminated by protecting both:

• 🔎 Kotlin: Before delivering items to Flutter (events.success(...))

• 🧠 Python: Before yield within generator, via inspector.is_active(...) guards

• ✂️ Removed useless variables like generatorRegistered = true from Kotlin, which were unused and showing linter warnings.

• 🧹 Prevented cancellation log spam:

• Used searchManager.has(searchId) before calling cancelSearch(...) to avoid:

• 🔄 Fixed Python generators still running yield after close attempt:

• Now intercepted precisely before results are sent in Kotlin and Python.

Improved #

• ✅ Flutter cancellation consistency: Only the latest searchId per stream type (search, related, artist, details) is now allowed to run or emit.

• ⚠ Better log annotations in Kotlin and Python, including:

• PythonEngineInspector: Yield guard check

• YTMusicAPI: Skipping stale result from cancelled stream

• Final StopIteration handling and shutdown trace for debugging

• 🚫 Suppressed Generator does not support close warning by properly handling fallback GeneratorExit in Python

NOT_WORKING-EOM

Added #

• Added proper streaminghandlers for (search, related songs, artist songs, song details)
• Added support for Lyrics from YTMUSIC request to YtFlutterMusicapi.fetchLyrics(songName, AristName) no time synced only.

Fixed #

• Multiple generators race conditions now engine checks the generators by ID.

• Error Handling: Improved error reporting in python Engine with logs stating with

• PythonEngine:

• PythonEngineInspector:

• PythonEngineExceptionsWarning:

• PythonEngineExceptionsCritical:

Active & Working

Fixed #

• Added proper python generator results inspector for all stream operations (search, related songs, artist songs, song details)

• Coroutine Management: Fixed the race conditions where the plugin mixes up two song details

• Error Handling: Improved error reporting in python and kotlin side

NOT_WORKING-EOM

Fixed #

• Stream Cancellation: Implemented proper cancellation handling for all stream operations (search, related songs, artist songs, song details)

• Coroutine Management: Added isActive checks before processing each stream item

• Resource Cleanup: Enhanced onCancel methods to properly clean up resources

• Error Handling: Improved error reporting for cancelled operations

• Clean up event sinks properly

Active & Working

Added #

• Support of fetching Artist Songs requires artistName="Obviously"

• New methods for exploring now supports 2 modes: mode=Batch (old) & mode=Stream (new) defualts to mode=auto ! required to explore the package

• Enhanced error recovery for interrupted streams

• Stream cancellation support with proper resource cleanup

Updated #

• Python-Kotlin bridge for efficient generator-based streaming

• Artist songs streaming architecture to use EventChannel instead of batch processing

• Example app with streaming visualization

Fixed #

• Memory management during long streaming sessions

• Thumbnail quality consistency across screens

• Race conditions in concurrent stream operations

• Resource leaks in generator-based implementations

Performance #

• Reduced initial latency from 1200ms to 300ms

• Consistent 50ms intervals between streamed items

• Lower memory footprint during streaming (45% reduction)

• Improved backpressure handling for slow clients

Breaking Changes #

• (New)streamArtistSongs now requires explicit cancellation handling

• Generator-based APIs may throw StopIteration exceptions

• Stream order is no longer guaranteed to match original API

Migration Notes #

• Clients should implement proper stream cancellation

• Batch processing now requires explicit collection of stream items of this package!

• Error handling should account for mid-stream failures

Deprecated — EOS

Updated #

• Updated README.md for the package.

Deprecated — EOS

Added #

-Introduced streamSearchResults functionality for real-time streaming of search results. This allows incremental delivery of song metadata instead of waiting for the entire batch, significantly improving responsiveness.

Deprecated — EOS

Fixed #

• Resolved issues in the Python mock/testing environment used during development.

Deprecated — EOS

Fixed #

• Corrected thumbnail quality mappings in the Python layer.
• LOW: w60-h60 (60x60 pixels)
• MED: w120-h120 (120x120 pixels)
• HIGH: w320-h320 (320x320 pixels)
• VERY_HIGH: w544-h544 (544x544 pixels)

Deprecated — EOS

Fixed #

• Addressed a memory overflow issue triggered by searchMusic and getRelatedSongs.

Added #

• Basic support for retrieving additional songs by an artist and discovering related artists. (Feature is still under development.)

Deprecated — EOS

Fixed #

• Corrected a Kotlin syntax error near line 441 that was preventing builds.

Deprecated — EOS

Added #

• Updated outdated documentation link in pubspec.yaml.

Updated #

• Updated yt-dlp to version 2024.06.30.
• Updated ytmusicapi Python backend to version 1.10.3.

---

Deprecated — EOS

Added #

• Initial stable release.
• YouTube Music search functionality using python's ytmusicapi and audio using yt-dlp.
• Related songs feature based on current track.
• Support for configurable audio and thumbnail quality.
• Cross-platform structure with Android support.
• Integrated Kotlin-Python bridge using Chaquopy for backend communication.