Music Library Import UX: Design an Onboarding Flow Listeners Can Finish

Music library import UX should help listeners choose their music, confirm its destination, and understand the outcome. Define those decisions before drawing screens. Treat account connection, transfer completion, and first playback as separate milestones so your interface never announces success before it can explain what happened.

For product managers adding import to streaming-service onboarding, the specification below maps listener questions to suggested copy, acceptance criteria, and proposed measurements. These recommendations describe a product experiment, not a proven completion lift. Apply custom interaction ideas to a native build; evaluate a fixed hosted flow against the same listener needs without assuming you can redesign it.

Decision	Custom native UX	Fixed hosted flow
Entry and skip	Design placement and return paths in your app	Design the surrounding entry and exit experience
Selection and confirmation	Specify screens around supported operations	Evaluate the supplied sequence and controls
Progress and results	Design presentation around available backend evidence	Check what the supplied pages communicate
Experiment scope	Test individual interface decisions	Test surrounding placement and supported copy changes

Define what a completed music library import means

Write three definitions into the product specification.

Transfer finished: the backend reports a terminal outcome for the attempted work. Results understood: the listener reaches a summary that distinguishes additions from exceptions. Imported music used: the listener starts playback of imported content inside your service, where your application can observe that action.

Do not collapse these into one success event. A listener might receive a useful partial import and start listening. Another might import everything but never open the destination library.

For each screen, document the listener’s question, the evidence the interface needs, and the condition that enables the next action. Treat the example copy here as proposed wording, not existing API fields or product screens.

A completion acceptance criterion could read: “The summary accounts for every selected item through an addition, an unresolved result, or an explicit exclusion.” Ask engineering to validate which outcomes the integration can distinguish before design assigns labels.

Keep implementation ownership separate. The existing playlist migration REST API tutorial addresses the engineering journey; this specification defines what listeners should understand along that journey.

Place the import entry point and offer a skip path

The entry screen answers: “Why should I do this now?” Try direct copy such as “Bring your music into your library,” with “Choose a music service” and “Skip for now” as separate actions. Avoid language that promises every favorite will arrive.

Use onboarding as one candidate placement and the library as a persistent return point. Spotify’s walkthrough, checked September 11, 2026, describes an import entry inside Your Library. That documents a consumer placement pattern, not evidence that the same placement will improve your funnel. See Spotify’s playlist import walkthrough.

Specify what skipping means: continue onboarding, leave import available later, and avoid marking the listener as a failed transfer. For a native implementation, preserve the entry context so the return action leads somewhere predictable.

Acceptance criteria: both actions support keyboard operation, the listener can continue without connecting an account, and the library exposes a discoverable route back to import.

Measure entry impressions, starts, skips, and later returns separately. Compare placements using eligible listeners as the denominator. A more prominent button might attract more starts without producing more useful imports.

Make source, destination and content selection explicit

The connection screen answers: “Which account am I using, and where will my music go?” Label source and destination with words. Keep the destination visible even when onboarding already establishes it. After connection, show enough confirmed account context to help the listener notice a mistake.

Suggested copy: “Choose where your music comes from.” On confirmation, use “Import into your library on this service.” Only display account details that the integration actually supplies.

MusicAPI’s authentication documentation requires accepted return URLs in the developer dashboard. That gives engineering a concrete dependency for returning listeners to your application after authentication. Include the return destination in your acceptance checklist and follow the authentication return URL configuration.

Specify distinct handling for connection success, cancellation, and failure. For a native build, retain previous selections when your application can safely do so. Explain which account needs attention instead of restarting the entire journey without context.

The selection screen answers: “What am I bringing over?” Separate content categories and use counts with explicit units. “Three playlists” describes a different selection from “Three songs.” Define whether selecting a playlist includes all its items and how the screen communicates an empty collection.

Check the source and destination against the supported music service features before offering a content type. The documentation states that service capabilities differ. Do not turn a generic library illustration into a promise that every operation works on every service.

Before starting, show a compact confirmation: source, destination, selected categories, and available counts. Use a specific action such as “Start import.” If an account change invalidates the selection, require a fresh confirmation.

Acceptance criteria: the listener can explain the transfer direction, identify the chosen content, and correct the selection before submitting it. Include fixtures for an empty source, an unavailable category, and a connection failure.

Explain progress and partial results without promising every item

The progress screen answers: “Is anything happening, and do I need to act?” Separate active work, waiting, and required action when backend evidence supports those distinctions.

Write status copy against real state transitions. “Finding matches” and “Adding music” should appear only when the integration can establish those activities. If the backend exposes less detail, use a broader truthful status. Do not animate a percentage toward completion without a defensible denominator.

For numeric progress, label the unit and stage. “Processing item 40 of 100” does not mean the destination already contains 40 additions. Avoid a countdown unless your team has evidence for its accuracy under the relevant conditions.

Make updates available to assistive technology without moving keyboard focus. W3C’s status-message guidance, checked September 11, 2026, explains this principle. Announce meaningful changes rather than every counter increment, and pair color indicators with text.

Do not promise that listeners can close the page, resume elsewhere, or receive a notification unless engineering has implemented and verified that behavior. Treat those as explicit requirements when your product needs them.

The results screen answers: “What arrived, and what needs attention?” Use a summary plus inspectable exceptions. An illustrative result might read: “92 tracks added. Eight tracks need attention.” Those numbers describe example copy, not measured transfer performance.

Apple’s music transfer instructions, checked September 11, 2026, distinguish completion from a result that needs match review. Use that distinction as a design reference. Do not infer that your integration offers Apple’s alternate-selection interaction.

For your own summary, distinguish match uncertainty from destination write failure whenever the backend supplies that evidence. Give each supported recovery action a precise label. Avoid “Retry everything” until engineering defines how repeated attempts affect content that already arrived.

Acceptance criteria: totals reconcile, exceptions remain visible, and the listener can open the destination library after a useful partial result. Use the existing music API error handling guide for the engineering discussion behind recovery behavior.

Choose native control or a fixed hosted transfer flow

Decide which listener-facing requirements your team must control before choosing the implementation route.

For a native build, specify screen order, navigation, selection defaults, status presentation, and recovery behavior as work your team owns. Ask engineering to map every interaction to documented capabilities. A design prototype does not establish support for cancellation, resumability, alternate matching, or duplicate prevention.

For a fixed hosted flow, evaluate the provided journey as a unit. Separate changes around the flow, such as your onboarding entry card, from changes inside it. Keep internal design proposals within the available branding and copy controls. Do not assume theming grants permission to add screens or reorder steps.

Use a review worksheet with three columns: required listener outcome, evidence that the flow supports it, and remaining product work. A requirement such as “listeners understand partial completion” concerns the outcome. “Show our custom exception drawer” prescribes an implementation that a fixed flow might not accommodate.

Before committing, walk through cancellation, no selectable content, connection failure, and partial results. Record gaps as implementation decisions. Do not turn a gap into a capability claim or hide it behind launch copy.

Measure abandonment and completion as a product experiment

Instrument the journey with events your application can actually observe. The following names describe proposed analytics events, not MusicAPI events or webhook payloads.

Proposed event	Trigger	Question it answers
import_entry_viewed	Eligible listener sees the entry	Did the listener encounter import?
import_started	Listener chooses to begin	Did the invitation prompt action?
accounts_connected	Required connections succeed	Did account connection complete?
selection_confirmed	Listener submits the selection	Did selection reach commitment?
transfer_finished	Backend establishes a terminal outcome	Did processing finish?
results_viewed	Listener sees the summary	Did the outcome reach the listener?
imported_content_played	Your service observes relevant playback	Did the imported content become useful?

Choose a measurement window and deduplication rule before launch. Keep transfer failures, partial outcomes, and listener exits separate. Report abandonment only after the chosen window closes; a listener who leaves a progress screen might return later.

Start with one hypothesis: an import invitation in an empty library will increase first playback of imported content among eligible listeners. Compare it with the current entry placement. Treat completion and playback improvements as outcomes to measure, not promises.

Track guardrails such as onboarding completion, connection errors, and support requests about missing music. For hosted journeys, document any unobservable steps rather than inferring them from entry and exit timestamps.

FAQ

Should import include an option to cancel the listener’s old subscription?

Keep subscription management outside this specification. Do not describe library import as account closure or subscription cancellation. If listeners confuse those tasks during research, clarify the distinction near confirmation and in support content.

What should a listener send support when an import looks wrong?

Provide a support reference from your application and ask which collection or item needs investigation. Define how support retrieves relevant diagnostic context. Do not ask listeners to paste authentication callbacks, access credentials, or private library exports into a general support form.

Turn these screen requirements into an integration review with the MusicAPI transfer service documentation. Map the listener journey to supported transfer behavior before committing your onboarding design.