If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/naman14/Timber shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Stale and unlicensed — last commit 3y ago

• 7 active contributors
• CI configured
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 59% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live naman14/Timber repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/naman14/Timber.

What it runs against: a local clone of naman14/Timber — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in naman14/Timber | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 1136 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of naman14/Timber. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/naman14/Timber.git
#   cd Timber
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of naman14/Timber and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "naman14/Timber(\\.git)?\\b" \\
  && ok "origin remote is naman14/Timber" \\
  || miss "origin remote is not naman14/Timber (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "app/src/main/java/com/naman14/timber/MusicService.java" \\
  && ok "app/src/main/java/com/naman14/timber/MusicService.java" \\
  || miss "missing critical file: app/src/main/java/com/naman14/timber/MusicService.java"
test -f "app/src/main/java/com/naman14/timber/MusicPlayer.java" \\
  && ok "app/src/main/java/com/naman14/timber/MusicPlayer.java" \\
  || miss "missing critical file: app/src/main/java/com/naman14/timber/MusicPlayer.java"
test -f "app/src/main/java/com/naman14/timber/activities/MainActivity.java" \\
  && ok "app/src/main/java/com/naman14/timber/activities/MainActivity.java" \\
  || miss "missing critical file: app/src/main/java/com/naman14/timber/activities/MainActivity.java"
test -f "app/src/main/aidl/com/naman14/timber/ITimberService.aidl" \\
  && ok "app/src/main/aidl/com/naman14/timber/ITimberService.aidl" \\
  || miss "missing critical file: app/src/main/aidl/com/naman14/timber/ITimberService.aidl"
test -f "app/src/main/java/com/naman14/timber/dataloaders/SongLoader.java" \\
  && ok "app/src/main/java/com/naman14/timber/dataloaders/SongLoader.java" \\
  || miss "missing critical file: app/src/main/java/com/naman14/timber/dataloaders/SongLoader.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1136 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1106d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/naman14/Timber"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Timber is a Material Design music player for Android that browses and plays local audio files from device storage, albums, artists, and playlists. It provides a modern Android UI with features like customizable now-playing screens, homescreen widgets, gesture controls, LastFM scrobbling, and Chromecast support—built entirely in Java as a native Android application. Monolithic Android app structure: MusicService (background service) handles playback via AIDL interface (ITimberService.aidl); Activities (MainActivity, NowPlayingActivity, PlaylistDetailActivity) in app/src/main/java/com/naman14/timber/activities/ drive UI; Adapters (SongsListAdapter, AlbumAdapter, ArtistAdapter, etc.) bind data to RecyclerViews; Helpers and utilities manage ContentProvider queries for media library. Assets include Material Design Icons font.

Android users who want a locally-focused, Material Design music player with playlist management and rich browsing capabilities. Android developers who want to learn Material Design patterns, music playback via MediaPlayer/MusicService, ContentProvider queries, and Android widget implementation.

This project is archived and no longer actively maintained (see README: 'no longer in active development'). It was last updated around 2015–2016 and has been superceded by TimberX. CI is set up (Travis CI badge present), but expect no security patches or bug fixes; use for learning or legacy maintenance only.

High risk for production use: unmaintained since ~2016, targets compileSdkVersion from that era, depends on deprecated libraries (Retrofit 1.9.0, OkHttp 2.x, UniversalImageLoader 1.9.4), and uses AIDL for service communication which is fragile. No visible test suite despite androidTest folder existing. Single-maintainer project with no recent commits.

Nothing—the project is dormant. The README explicitly directs users to TimberX instead. No active development, PRs, or issues are being worked on.

git clone https://github.com/naman14/Timber.git
cd Timber
cd app
./gradlew build
./gradlew installDebug  # requires Android device/emulator

Requires Android SDK (minSdkVersion 16, targetSdkVersion from build.gradle), Android Studio or command-line Gradle tools, and a connected device or emulator.

Daily commands:

./gradlew assembleDebug  # build debug APK to app/build/outputs/apk/debug/
./gradlew installDebug   # install on connected device
adb shell am start -n naman14.timber/.activities.MainActivity  # launch app

Or open in Android Studio → Run → Run 'app' to build, install, and launch via IDE.

• app/src/main/java/com/naman14/timber/MusicService.java — Core background service managing music playback state, queue, and IPC communication with UI; all playback logic routes through here
• app/src/main/java/com/naman14/timber/MusicPlayer.java — Direct MediaPlayer wrapper handling actual audio playback, seeking, volume; abstracts Android audio framework for the service
• app/src/main/java/com/naman14/timber/activities/MainActivity.java — Primary entry point and main UI container; hosts fragment navigation and communicates with MusicService via AIDL
• app/src/main/aidl/com/naman14/timber/ITimberService.aidl — AIDL interface contract for IPC between UI activities and background MusicService; defines all playback control methods
• app/src/main/java/com/naman14/timber/dataloaders/SongLoader.java — Cursor loader querying Android MediaStore for songs; foundational data layer for populating all music lists
• app/src/main/java/com/naman14/timber/adapters/BaseSongAdapter.java — Base RecyclerView adapter for all song list presentations; provides UI binding pattern used across all music list fragments
• app/build.gradle — Gradle build configuration; declares all dependencies, SDK versions, and Firebase/Crashlytics integration

Add a new music browsing fragment (e.g., Genres)

1. Create a new CursorLoader in dataloaders/ (e.g., GenreLoader.java) that queries MediaStore for genres (app/src/main/java/com/naman14/timber/dataloaders/GenreLoader.java)
2. Create a new fragment extending existing music fragment pattern (similar to SongsFragment.java) (app/src/main/java/com/naman14/timber/fragments/GenreFragment.java)
3. Create an adapter extending BaseSongAdapter or BaseQueueAdapter to display genres (app/src/main/java/com/naman14/timber/adapters/GenreAdapter.java)
4. Add the fragment to the ViewPager tab menu in MainActivity.java and wire up loader callbacks (app/src/main/java/com/naman14/timber/activities/MainActivity.java)

Add a new playback control feature (e.g., repeat modes, shuffle)

1. Add new AIDL method to the ITimberService interface (e.g., setRepeatMode(int mode)) (app/src/main/aidl/com/naman14/timber/ITimberService.aidl)
2. Implement the method in MusicService.java to manage internal state and forward to MusicPlayer.java (app/src/main/java/com/naman14/timber/MusicService.java)
3. Update MusicPlayer.java to handle the logic (e.g., queue wrapping on repeat) (app/src/main/java/com/naman14/timber/MusicPlayer.java)
4. Add UI controls in the relevant activity (e.g., NowPlayingActivity.java) to call the AIDL method (app/src/main/java/com/naman14/timber/activities/NowPlayingActivity.java)

Fetch additional metadata from Last.fm (e.g., track duration, popularity)

1. Create a new POJO model in lastfmapi/models/ (e.g., TrackInfo.java) matching Last.fm JSON response (app/src/main/java/com/naman14/timber/lastfmapi/models/TrackInfo.java)
2. Add new Retrofit endpoint to LastFmRestService.java for the track.getInfo API call (app/src/main/java/com/naman14/timber/lastfmapi/LastFmRestService.java)
3. Implement a new callback listener (e.g., TrackInfoListener.java) following the pattern of AlbumInfoListener.java (app/src/main/java/com/naman14/timber/lastfmapi/callbacks/TrackInfoListener.java)
4. Call the endpoint from LastFmClient.java and cache the result; use callback to update UI in the fragment (app/src/main/java/com/naman14/timber/lastfmapi/LastFmClient.java)

Add a new settings preference (e.g., audio quality, scrobbling behavior)

1. Define the preference key and default in the fragment layout or preferences logic (app/src/main/java/com/naman14/timber/fragments/SettingsFragment.java)
2. Update SettingsActivity.java to

No explicit environment config: Assumes Android SDK is installed and ANDROID_HOME is set. Deprecated libraries: Retrofit 1.9.0 and OkHttp 2.x are pre-2015 versions with known bugs and security issues—do NOT use in production. LastFM API key: LastFM scrobbling will fail silently if no API key is configured in the app. ProGuard minification disabled: minifyEnabled false in build.gradle, so APK will be large. RenderScript quirk: renderscriptTargetApi 16 with renderscriptSupportModeEnabled false is hardcoded—don't change without testing on older devices. AIDL service complexity: If you modify ITimberService.aidl, you must rebuild the project; AIDL stubs are not auto-refreshed in all IDEs.

• Android Service + AIDL (Inter-Process Communication) — MusicService runs in background via AIDL interface; understanding Services and AIDL stubs is essential to modify playback behavior without killing the service.
• MediaPlayer Lifecycle & State Machine — MusicService wraps MediaPlayer; knowing prepare(), start(), pause(), stop() states and transitions prevents race conditions in playback.
• ContentProvider + MediaStore Queries — Timber queries Android's MediaStore ContentProvider to enumerate songs, albums, artists; this is the pattern for accessing device audio files.
• RecyclerView Adapter Pattern — Adapters (BaseSongAdapter, AlbumAdapter) bind MediaStore data to RecyclerViews; understanding ViewHolder pattern is critical for efficient list rendering.
• Material Design & Dynamic Color Theming (Palette API) — BaseThemedActivity uses AndroidX Palette to extract dominant colors from album artwork and apply them dynamically; demonstrates modern Material color adaptation.
• Android AppWidget (Homescreen Widgets) — Timber provides homescreen widgets for playback control; requires understanding RemoteViews, AppWidgetProvider, and PendingIntents for safe IPC.
• Gesture Detection & Touch Event Handling — NowPlayingActivity implements gesture swipes for track switching; understanding GestureDetector and MotionEvent is needed to modify gesture behavior.

• naman14/TimberX — Official successor to Timber—rewritten in Kotlin with modern architecture; migrate here if starting a new Android music player project.
• CyanogenMod/android_packages_apps_Eleven — Timber's direct ancestor and inspiration; study Eleven's playback logic and playlist handling if you need reference implementations.
• paulfryer/Material-Music-Player — Alternative Material Design music player for Android with similar feature set; compare UI patterns and ContentProvider usage.
• guolindev/PermissionX — Relevant for Android 6.0+ runtime permissions; Timber uses Nammu library (dated) for permissions—PermissionX is a modern replacement.
• wasabeef/glide — Modern image loading library as alternative to the deprecated UniversalImageLoader used in Timber for album art caching.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Migrate from deprecated Retrofit 1.9.0 to Retrofit 2.x with OkHttp3

The project uses Retrofit 1.9.0 and OkHttp 2.x which are deprecated and no longer maintained. This creates security vulnerabilities and incompatibility with modern Android APIs. Retrofit 2.x provides better performance, modern Java features, and proper dependency management. This is a high-impact refactoring that will improve security and maintainability.

• [ ] Update app/build.gradle: Replace 'com.squareup.retrofit:retrofit:1.9.0' with 'com.squareup.retrofit2:retrofit:2.9.0' and add okhttp3 dependency
• [ ] Update all import statements from 'retrofit.client' to 'retrofit2' across dataloaders and network-related classes (e.g., AlbumLoader.java, ArtistLoader.java)
• [ ] Refactor REST API interfaces to use Retrofit 2 annotations (@GET, @POST with Call<T> return types instead of Callback patterns)
• [ ] Update callback implementations in dataloaders to use Retrofit 2's Call.enqueue() pattern
• [ ] Test all data loading functionality (albums, artists, songs, playlists) in both debug and release builds

Add unit tests for MusicService and MusicPlayer core functionality

The project has only one test file (ApplicationTest.java) which is outdated. MusicService.java and MusicPlayer.java are critical components handling playback, queue management, and AIDL service communication. Adding unit tests for these will prevent regressions in core functionality and serve as documentation for API contract behavior.

• [ ] Create app/src/test/java/com/naman14/timber/MusicServiceTest.java to test playback control methods (play, pause, stop, seek)
• [ ] Create app/src/test/java/com/naman14/timber/MusicPlayerTest.java to test track initialization and state management
• [ ] Add mock tests for AIDL service callbacks using Mockito (add 'org.mockito:mockito-core' to testImplementation in build.gradle)
• [ ] Test queue management scenarios (next, previous, shuffle, repeat modes)
• [ ] Update app/src/androidTest/java/com/naman14/timber/ApplicationTest.java or remove it if superseded by proper unit tests

Convert legacy AIDL files to Android Kotlin Serialization and add proper service binding tests

The project uses AIDL (ITimberService.aidl, MusicPlaybackTrack.aidl) for inter-process communication, which is legacy and error-prone. Additionally, there are no tests for the service binding mechanism. Converting to modern Kotlin serialization with proper binding tests will make the codebase more maintainable and ensure WearBrowserService.java communication works reliably.

• [ ] Create app/src/androidTest/java/com/naman14/timber/MusicServiceBindingTest.java to test service connection and IPC
• [ ] Add instrumented tests that verify MusicPlaybackTrack data serialization/deserialization
• [ ] Document the migration plan in a new CONTRIBUTING.md or update README.md with a 'Modernization Roadmap' section explaining why AIDL will be replaced
• [ ] Keep existing AIDL files functional for backward compatibility while new tests provide safety net for refactoring
• [ ] Test integration with WearBrowserService.java to ensure Wear OS communication remains functional

• Add unit tests for BaseSongAdapter.java and SongsListAdapter.java—currently no test coverage visible despite androidTest/ folder existing; start by writing adapter binding tests.
• Migrate from deprecated Retrofit 1.9.0 to Retrofit 2.x to enable LastFM scrobbling without network timeouts and security warnings.
• Add Kotlin extension functions in app/src/main/java/com/naman14/timber/helpers/ to simplify ContentProvider queries (wrap MediaStore.Audio.* calls) and reduce boilerplate in adapters.

• High · Outdated Retrofit Library with Known Vulnerabilities — app/build.gradle - dependencies section. The codebase uses Retrofit 1.9.0 (released 2014) and OkHttp 2.x, both of which are extremely outdated and contain multiple known security vulnerabilities including improper TLS certificate validation, HTTP/2 support issues, and potential Man-in-the-Middle (MITM) attack vectors. Fix: Upgrade to Retrofit 2.9.0+ and OkHttp 4.x or later. Retrofit 1.x reached end-of-life in 2015. Ensure proper certificate pinning implementation for sensitive API calls.
• High · Outdated Universal Image Loader Library — app/build.gradle - dependencies section. The project uses Universal Image Loader 1.9.4 (2014), which is abandoned and may have unpatched vulnerabilities in image processing and caching mechanisms. This could lead to information disclosure or code execution. Fix: Migrate to modern image loading libraries such as Glide 4.x+, Picasso 2.8.1+, or Coil. These libraries receive regular security updates and better handle edge cases.
• High · ProGuard Minification Disabled in Release Build — app/build.gradle - buildTypes.release section. The release build has minifyEnabled set to false, which means the APK will contain unobfuscated Java code. This makes reverse engineering significantly easier and exposes sensitive logic, API endpoints, and credentials to attackers. Fix: Enable minification (minifyEnabled true) and proper ProGuard/R8 configuration. Ensure keep rules are properly configured to maintain functionality while obfuscating sensitive code. Review and test thoroughly after enabling.
• Medium · Firebase Crashlytics Integration Without Explicit Security Review — app/build.gradle - plugins section (com.google.firebase.crashlytics). The project integrates Firebase Crashlytics which sends crash reports including stack traces to Google's servers. While Firebase has security controls, crash reports may inadvertently leak sensitive information like API keys, user data, or internal application logic. Fix: Review Firebase/Crashlytics privacy and security settings. Implement custom exception handling to sanitize stack traces before sending to Crashlytics. Consider implementing data masking for sensitive information in crash reports.
• Medium · Missing Explicit Security Permissions Review — app/src/main/AndroidManifest.xml. While the AndroidManifest.xml wasn't fully visible, a music player application typically requires permissions like READ_EXTERNAL_STORAGE, INTERNET, and potentially camera/microphone. The principle of least privilege should be carefully applied. Fix: Audit all declared permissions and justify each one. Implement runtime permission requests for Android 6.0+. Request only necessary permissions and consider using scoped storage instead of READ_EXTERNAL_STORAGE for Android 11+.
• Medium · Potential SQL Injection in Data Loaders — app/src/main/java/com/naman14/timber/dataloaders/. The dataloaders package (AlbumLoader, ArtistLoader, SongLoader, etc.) likely contains database queries. Without seeing the implementation, there's risk of SQL injection if user input is not properly parameterized. Fix: Ensure all database queries use parameterized queries or prepared statements. Never concatenate user input directly into SQL queries. Use ContentResolver with proper selection arguments instead of raw SQL.
• Medium · Unencrypted Network Communications with Legacy HTTP — app/src/main/java/com/naman14/timber/dialogs/LastFmLoginDialog.java and cast/WebServer.java. The combination of outdated Retrofit/OkHttp and no visible certificate pinning implementation suggests potential unencrypted or weakly encrypted network communications, particularly with LastFM API integration. Fix: Implement certificate pinning using OkHttp's CertificatePinner. Force HTTPS for all network calls. Use modern TLS versions (1.2+) and disable SSL/TLS fallback mechanisms.
• Medium · WebServer Implementation Without Visible Security Controls — undefined. The WebServer.java in cast module (likely for Google Cast integration) may expose API endpoints without proper authentication or authorization mechanisms, potentially Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.