Radioplayer Developer Reference

Migration Guide — SDK Annotations 1.2.x → 2.0.0

Technical reference for Radioplayer partner integrations.

Version

Current

Document type

API / SDK reference

Audience

Radioplayer partner engineering teams

This document covers every breaking and non-breaking change to the annotation API between the 1.2.x series and 2.0.0. Changes are derived solely from the sdkAnnotation module's source history.

Table of Contents

1. Quick Summary
2. Removed Annotations

3. Radio Annotations

   • RadioStart
   • RadioStop
   • RadioPause
   • RadioSeek
   • RadioSkip
   • RadioError

4. Podcast Annotations

   • PodcastStart
   • PodcastStop
   • PodcastPause
   • PodcastSeek
   • PodcastSkip
   • PodcastError

5. Action Annotations

   • ActionRecClicked
   • MetadataUpdate

6. Enum Changes

   • RadioMode
7. Unchanged Annotations
8. Migration Checklist

1. Quick Summary

2. Removed Annotations

@ActionRating — REMOVED

The entire ActionRating annotation has been deleted. No replacement exists.

Action required: remove all usages of @ActionRating from your codebase.

// 1.2.x — DELETE this
@ActionRating(type = "...", uiSource = "...", mediaId = "...",
    mediaType = "...", bearer = "...", like = "...")
public void onRating() { ... }

3. Radio Annotations

@RadioStart

// 1.2.x
@RadioStart(
    mediaId    = "{radioStations.get(i).getMediaId()}",
    bearer     = "{radioStations.get(i).getBearers().get(0).getId()}",
    position   = "0",
    output     = "speaker",
    syncInfo   = "",
    mediaSource = "{MediaSource.RADIO_ON_BOARD}",
    radioMode  = "{RadioMode.AM_FM}",
    volume     = "{volume}",
    countryCode = "276"
)

// 2.0.0
@RadioStart(
    rpuid       = "{radioStations.get(i).getMediaId()}",
    bearer      = "{radioStations.get(i).getBearers().get(0).getId()}",
    radioMode   = "{RadioMode.DAB}",
    volume      = "{volume}",
    countryCode = "276"
)

@RadioStop

// 1.2.x
@RadioStop(
    mediaId     = "380101",
    bearer      = "dab:ce1.c185.c500.0",
    position    = "100",
    output      = "speaker",
    syncInfo    = "",
    mediaSource = "{MediaSource.RADIO_ON_BOARD}",
    radioMode   = "{RadioMode.DAB}",
    volume      = "{volume}",
    countryCode = "276"
)

// 2.0.0
@RadioStop(
    rpuid       = "380101",
    bearer      = "dab:ce1.c185.c500.0",
    radioMode   = "{RadioMode.DAB}",
    volume      = "{volume}",
    countryCode = "276"
)

@RadioPause

// 1.2.x
@RadioPause(mediaId = "380101", bearer = "dab:ce1.c185.c500.0",
    position = "33", output = "speaker", syncInfo = "")

// 2.0.0
@RadioPause(rpuid = "380101", bearer = "dab:ce1.c185.c500.0", countryCode = "528")

@RadioSeek

// 1.2.x
@RadioSeek(mediaId = "380101", bearer = "fm:87.5", position = "1000",
    output = "speaker", seekType = "{SeekStatus.FORWARD}")

// 2.0.0
@RadioSeek(rpuid = "380101", bearer = "fm:87.5", countryCode = "276",
    seekType = "{SeekStatus.FORWARD}")

@RadioSkip

This annotation has the most renamed fields in the radio group.

// 1.2.x
@RadioSkip(mediaId = "380101", bearer = "dab:ce1.c185.c500.0",
    position = "1000", output = "speaker", index = "2",
    skipType = "{SkipStatus.NEXT}")

// 2.0.0
@RadioSkip(newRpuid = "380201", newBearer = "dab:ce1.c185.c501.0",
    countryCode = "276", skipType = "{SkipStatus.NEXT}")

@RadioError

// 1.2.x
@RadioError(mediaId = "380101", position = "1000",
    output = "speaker", reason = "Stream error")

// 2.0.0
@RadioError(rpuid = "380101", bearer = "dab:ce1.c185.c500.0",
    reason = "Stream error")

4. Podcast Annotations

All podcast annotations share a common pattern of changes:

• mediaId is replaced by an ID type appropriate to the content (crid or newCrid).
• countryCode is now mandatory (was optional with default "UNSPECIFIED").
• position is now optional (was mandatory).
• output is removed from all podcast annotations.
• syncInfo is removed where present.

@PodcastStart

// 1.2.x
@PodcastStart(mediaId = "crid://bbc.co.uk/b006qykl", countryCode = "826",
    position = "0", output = "speaker", syncInfo = "")

// 2.0.0
@PodcastStart(crid = "crid://bbc.co.uk/b006qykl", countryCode = "826")

@PodcastStop

// 1.2.x
@PodcastStop(mediaId = "crid://bbc.co.uk/b006qykl", countryCode = "826",
    position = "300", output = "speaker", syncInfo = "")

// 2.0.0
@PodcastStop(crid = "crid://bbc.co.uk/b006qykl", countryCode = "826",
    position = "300")

@PodcastPause

// 1.2.x
@PodcastPause(mediaId = "crid://bbc.co.uk/b006qykl", countryCode = "826",
    position = "120", output = "speaker", syncInfo = "")

// 2.0.0
@PodcastPause(crid = "crid://bbc.co.uk/b006qykl", countryCode = "826",
    position = "120")

@PodcastSeek

// 1.2.x
@PodcastSeek(mediaId = "crid://bbc.co.uk/b006qykl", countryCode = "826",
    position = "1000", output = "speaker",
    seekType = "{SeekStatus.BACKWARD}")

// 2.0.0
@PodcastSeek(crid = "crid://bbc.co.uk/b006qykl", countryCode = "826",
    position = "1000", seekType = "{SeekStatus.BACKWARD}")

@PodcastSkip

// 1.2.x
@PodcastSkip(mediaId = "crid://bbc.co.uk/b007jfnp", countryCode = "826",
    position = "0", output = "speaker", index = "3",
    skipType = "{SkipStatus.NEXT}")

// 2.0.0
@PodcastSkip(newCrid = "crid://bbc.co.uk/b007jfnp", countryCode = "826",
    skipType = "{SkipStatus.NEXT}")

@PodcastError

// 1.2.x
@PodcastError(mediaId = "crid://bbc.co.uk/b006qykl", position = "1000",
    output = "speaker", reason = "Buffer underrun")

// 2.0.0
@PodcastError(crid = "crid://bbc.co.uk/b006qykl", reason = "Buffer underrun")

5. Action Annotations

@ActionRecClicked

A new mandatory field clickedRecType has been added.

clickedRecType accepts the string "STATION" or "EPISODE".

// 1.2.x
@ActionRecClicked(type = "RecClicked", uiSource = "Recommendation",
    clickedRecId = "1234")

// 2.0.0
@ActionRecClicked(type = "RecClicked", uiSource = "Recommendation",
    clickedRecId = "1234", clickedRecType = "STATION")

@MetadataUpdate

This annotation was significantly extended: two new mandatory fields added and parameter naming aligned to camelCase.

// 1.2.x
@MetadataUpdate(
    artist          = "{currentOnAirInfo.getSongArtist()}",
    song            = "{currentOnAirInfo.getSongName()}",
    album           = "{currentOnAirInfo.getAlbum()}",
    show            = "{currentOnAirInfo.getShowName()}",
    schedule_start  = "{currentOnAirInfo.getSongStart()}",
    schedule_stop   = "{currentOnAirInfo.getSongEnd()}"
)

// 2.0.0
@MetadataUpdate(
    mediaId        = "{this.getMediaId()}",
    bearer         = "{this.getBearer()}",
    artist         = "{currentOnAirInfo.getSongArtist()}",
    song           = "{currentOnAirInfo.getSongName()}",
    album          = "{currentOnAirInfo.getAlbum()}",
    show           = "{currentOnAirInfo.getShowName()}",
    scheduleStart  = "{currentOnAirInfo.getSongStart()}",
    scheduleStop   = "{currentOnAirInfo.getSongEnd()}"
)

6. Enum Changes

RadioMode

// 1.2.x
radioMode = "{RadioMode.AM_FM}"   // covers both AM and FM

// 2.0.0 — choose the specific band
radioMode = "{RadioMode.AM}"

// or
radioMode = "{RadioMode.FM}"

7. Unchanged Annotations

The following annotations received only Javadoc improvements and are fully backward-compatible :

8. Migration Checklist

Use this checklist to audit your codebase when upgrading.

Global renames (safe to do with find-and-replace)

• @ActionRating(...) → delete entirely
• mediaId = → rpuid = in all radio annotations (@RadioStart, @RadioStop, @RadioPause, @RadioSeek, @RadioError)
• mediaId = → newRpuid = in @RadioSkip
• bearer = → newBearer = in @RadioSkip
• mediaId = → crid = in podcast annotations (@PodcastStart, @PodcastStop, @PodcastPause, @PodcastSeek, @PodcastError)
• mediaId = → newCrid = in @PodcastSkip
• schedule_start = → scheduleStart = in @MetadataUpdate
• schedule_stop = → scheduleStop = in @MetadataUpdate
• RadioMode.AM_FM → RadioMode.AM or RadioMode.FM (verify which band applies)

Parameters to remove

• Remove position = from @RadioStart, @RadioStop, @RadioPause, @RadioSeek, @RadioSkip
• Remove output = from all radio and podcast annotations
• Remove syncInfo = from @RadioStart, @RadioStop, @RadioPause, @PodcastStart, @PodcastStop, @PodcastPause
• Remove mediaSource = from @RadioStart, @RadioStop
• Remove index = from @RadioSkip, @PodcastSkip

Parameters to add or make mandatory

• Add countryCode = (mandatory) to every annotation where it was previously optional or absent
• Add clickedRecType = ("STATION" or "EPISODE") to @ActionRecClicked
• Add mediaId = to @MetadataUpdate

Enum audit

• Replace every RadioMode.AM_FM reference with the correct split value (RadioMode.AM or RadioMode.FM)