music

---
sidebar_position: 1
title: Music
---

# TSMusic

Manage music playback and file operations on watch devices, including fetching music lists, pushing/deleting tracks, controlling playback, and adjusting volume.

## Prerequisites

- Device must be connected and authenticated
- For push operations, music files must exist locally and be readable
- All callbacks execute on the main thread

## Data Models

### TSMusicModel

Represents music information and playback state on the watch device.

| Property | Type | Description |
|----------|------|-------------|
| `musicId` | `NSString *` | Unique identifier for the music track, used for device management |
| `filePath` | `NSString *` | Local file path of the music file, required for push operations |
| `title` | `NSString *` | Music track title, max 64 bytes, displayed on device |
| `artist` | `NSString *` | Artist or performer name, max 64 bytes, displayed on device |
| `duration` | `NSTimeInterval` | Total duration in seconds, used for progress calculation |
| `currentTime` | `NSTimeInterval` | Current playback position in seconds, range 0 to duration |
| `playbackStatus` | `TSMusicPlaybackStatus` | Current playback state (stopped, playing, or paused) |

## Enumerations

### TSMusicPlaybackStatus

Defines playback status of music on the watch device.

| Value | Description |
|-------|-------------|
| `TSMusicPlaybackStatusStopped` | Music is stopped |
| `TSMusicPlaybackStatusPlaying` | Music is playing |
| `TSMusicPlaybackStatusPaused` | Music is paused |

## Callback Types

### TSMusicListBlock

```objc
typedef void (^TSMusicListBlock)(`NSArray<TSMusicModel *>` *_Nullable musics, NSError *_Nullable error);

Callback for music list retrieval operations.

Parameter	Type	Description
musics	NSArray<TSMusicModel *> *	Array of music models, empty if retrieval fails
error	NSError *	Error information if failed, nil if successful

API Reference

Fetch all music from device

- (void)fetchAllMusics:(nonnull TSMusicListBlock)completion;

Retrieves all music tracks currently stored on the watch device.

Parameter	Type	Description
completion	TSMusicListBlock	Callback with array of all music models

Example:

[musicInterface fetchAllMusics:^(`NSArray<TSMusicModel *>` *musics, NSError *error) {
    if (error) {
        TSLog(@"Failed to fetch musics: %@", error.localizedDescription);
        return;
    }
    TSLog(@"Found %lu musics", (unsigned long)musics.count);
    for (TSMusicModel *music in musics) {
        TSLog(@"Music: %@ by %@", music.title, music.artist);
    }
}];

Delete music from device

- (void)deleteMusic:(`TSMusicModel *`)music completion:(nullable TSCompletionBlock)completion;

Removes a specific music track from the watch device.

Parameter	Type	Description
music	TSMusicModel *	Music model to delete, must contain valid musicId
completion	TSCompletionBlock	Callback with success status and error info

Example:

TSMusicModel *musicToDelete = [[TSMusicModel alloc] init];
musicToDelete.musicId = @"music_123";

[musicInterface deleteMusic:musicToDelete completion:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Music deleted successfully");
    } else {
        TSLog(@"Failed to delete music: %@", error.localizedDescription);
    }
}];

Push music to device

- (void)pushMusic:(`TSMusicModel *`)music
         progress:(nullable TSFileTransferProgressBlock)progress
          success:(nullable TSFileTransferSuccessBlock)success
          failure:(nullable TSFileTransferFailureBlock)failure;

Transfers a music track to the watch device with progress tracking.

Parameter	Type	Description
music	TSMusicModel *	Music model with valid filePath pointing to music file
progress	TSFileTransferProgressBlock	Called multiple times with transfer progress (0-100)
success	TSFileTransferSuccessBlock	Called when push completes successfully
failure	TSFileTransferFailureBlock	Called when push fails or is canceled

Example:

TSMusicModel *music = [[TSMusicModel alloc] init];
music.filePath = @"/path/to/music.mp3";
music.title = @"Song Title";
music.artist = @"Artist Name";

[musicInterface pushMusic:music
                progress:^(NSInteger progress, TSFileTransferStatus status) {
    TSLog(@"Push progress: %ld%%", (long)progress);
} success:^(TSFileTransferStatus status) {
    TSLog(@"Music pushed successfully");
} failure:^(TSFileTransferStatus status, NSError *error) {
    TSLog(@"Push failed: %@", error.localizedDescription);
}];

Cancel music push

- (void)cancelPushMusic:(nullable TSCompletionBlock)completion;

Cancels the currently ongoing music push operation and cleans up temporary files.

Parameter	Type	Description
completion	TSCompletionBlock	Callback with cancellation status

Example:

[musicInterface cancelPushMusic:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Push operation canceled");
    } else {
        TSLog(@"Failed to cancel: %@", error.localizedDescription);
    }
}];

Play music

- (void)playMusic:(nullable TSCompletionBlock)completion;

Sends play command to start or resume music playback on the device.

Parameter	Type	Description
completion	TSCompletionBlock	Callback with command execution status

Example:

[musicInterface playMusic:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Playback started");
    }
}];

Pause music

- (void)pauseMusic:(nullable TSCompletionBlock)completion;

Sends pause command to pause current music playback on the device.

Parameter	Type	Description
completion	TSCompletionBlock	Callback with command execution status

Example:

[musicInterface pauseMusic:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Playback paused");
    }
}];

Play next track

- (void)playNextMusic:(nullable TSCompletionBlock)completion;

Sends command to skip to the next music track on the device.

Parameter	Type	Description
completion	TSCompletionBlock	Callback with command execution status

Example:

[musicInterface playNextMusic:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Skipped to next track");
    }
}];

Play previous track

- (void)playPreviousMusic:(nullable TSCompletionBlock)completion;

Sends command to skip to the previous music track on the device.

Parameter	Type	Description
completion	TSCompletionBlock	Callback with command execution status

Example:

[musicInterface playPreviousMusic:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Skipped to previous track");
    }
}];

Increase volume

- (void)increaseVolume:(nullable TSCompletionBlock)completion;

Increases device volume by one step as determined by device firmware.

Parameter	Type	Description
completion	TSCompletionBlock	Callback with command execution status

Example:

[musicInterface increaseVolume:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Volume increased");
    }
}];

Decrease volume

- (void)decreaseVolume:(nullable TSCompletionBlock)completion;

Decreases device volume by one step as determined by device firmware.

Parameter	Type	Description
completion	TSCompletionBlock	Callback with command execution status

Example:

[musicInterface decreaseVolume:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Volume decreased");
    }
}];

Mute device

- (void)muteVolume:(nullable TSCompletionBlock)completion;

Mutes the device while preserving current volume level for later restoration.

Parameter	Type	Description
completion	TSCompletionBlock	Callback with command execution status

Example:

[musicInterface muteVolume:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Device muted");
    }
}];

Unmute device

- (void)unmuteVolume:(nullable TSCompletionBlock)completion;

Unmutes the device and restores the volume level active before muting.

Parameter	Type	Description
completion	TSCompletionBlock	Callback with command execution status

Example:

[musicInterface unmuteVolume:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Device unmuted");
    }
}];

Set volume to specific value

- (void)setVolume:(NSInteger)volume completion:(nullable TSCompletionBlock)completion;

Sets device volume to a specific value between 0 and 100.

Parameter	Type	Description
volume	NSInteger	Target volume value, range [0, 100], values outside range are clamped
completion	TSCompletionBlock	Callback with command execution status

Example:

[musicInterface setVolume:50 completion:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Volume set to 50");
    }
}];

Important Notes

1. All callbacks execute on the main thread; perform UI updates directly without additional dispatch
2. Music file paths must be valid and readable when pushing; verify file existence before operations
3. Only one push operation can be active at a time; cancel ongoing operations before starting new ones
4. The musicId property is required for delete operations; ensure it matches device records
5. Volume values are automatically clamped to [0, 100] range; no validation errors for out-of-range input
6. Playback control commands (play, pause, next, previous) require music to be present on device
7. Mute state is independent of volume level; unmute restores the previous volume without requiring explicit set