Amphibian

Sound­Cloud­ed

For ExpressionEngine 6, ExpressionEngine 3+, ExpressionEngine 2 • Current Version: 1.1.1

As of August 2021, Sound­Cloud­ed has been dis­con­tin­ued due to changes in Sound­Cloud’s API autho­riza­tion flow.

Sound­Cloud­ed is a mod­ule and field­type for Expres­sio­nEngine® which gives you full access to the Sound­Cloud API for select­ing and dis­play­ing tracks, favourites, or playlists from any Sound­Cloud account. Embed play­er wid­gets with zero effort and many cus­tomiz­able options, or use the full suite of includ­ed vari­ables to show only select data about your sounds, and even build your own audio player.

Using the field­type, set­up a chan­nel, Grid, Matrix, or Low Vari­ables field to dis­play a menu of tracks, favourites, or playlists from any Sound­Cloud user you spec­i­fy. Or use the mod­ule’s tem­plate tags to loop through all avail­able tracks, favourites or playlists from any Sound­Cloud user you spec­i­fy, like chan­nel entries. You can also fetch com­plete data for a spe­cif­ic track or playlist using only its URL.

Requirements

  • Expres­sio­nEngine 2.8.0 or greater
  • cURL PHP extension

Documentation

Instal­la­tion

Upload the includ­ed sound­cloud­ed fold­er to your /​system/​expressionengine/​third_​party/​direc­to­ry, then acti­vate the mod­ule and field­type from the Add-Ons → Mod­ules menu or the Add-Ons → Field­types menu.

Field­type

The Sound­Cloud­ed field­type accepts three settings:

  • the type of item you want to choose from in your field (tracks, favourites, or playlists)
  • the Sound­Cloud User­name from which you’d like to dis­play said items
  • the num­ber of items you’d like to dis­play in the field­’s drop­down menu (max­i­mum is 8000, though many servers will time­out before fetch­ing that many items from the API)

Note that pri­vate sounds are not returned via the pub­lic API, so only pub­lic sounds will be displayed.

The field­type is also com­pat­i­ble with Grid, Matrix, and Low Vari­ables.

Field­type tag pair

The Sound­Cloud­ed field­type tag pair accepts all the same para­me­ters, and con­tains all the same vari­ables, as the mod­ule tem­plate tags, with the excep­tion of the count, total_results, and pagination tags, as the field­type will only ever return a sin­gle track or playlist.

Tem­plate Tags

{exp:soundclouded:tracks}

This tag pair out­puts Sound­Cloud tracks based on the para­me­ters pro­vid­ed to it. It has sev­er­al parameters:

  • user(required) the user­name of the Sound­Cloud account you wish to get retrieve tracks from.
  • include_comments – whether or not to fetch any com­ments asso­ci­at­ed with each track. Default: no.
  • limit – the num­ber of tracks to return per-page. Default: 50.
  • paginate – where to place the pag­i­na­tion markup. Can be top, bot­tom, or both.

The fol­low­ing para­me­ters apply only to the wid­get embed code — if you won’t be using the play­er wid­get, you can ignore these:

  • widget_auto_play – whether or not the wid­get should auto­mat­i­cal­ly play when loaded. Default: no.
  • widget_class – class name to apply to the wid­get iframe.
  • widget_color6‑character hex code to use as the high­light colour in the wid­get (has no effect when using the visu­al” widget).
  • widget_dark_mode – whether or not the wid­get should use light colours on a trans­par­ent back­ground (will only take effect if your wid­get is exact­ly 20 pix­els high). Default: no.
  • widget_height – height of the wid­get, expressed in pix­els or a per­cent­age. Default: 300.
  • widget_hide_related – whether or not to show relat­ed tracks in the wid­get when paused or com­plet­ed (visu­al wid­get only). Default: no.
  • widget_show_artwork – whether or not to show the track art­work (has no effect when using the visu­al” wid­get). Default: yes.
  • widget_show_buying – whether or not to show the Buy” icon (if enabled). Default: yes.
  • widget_show_comments – whether or not to show com­ments in the wid­get wave­form. Default: yes.
  • widget_show_download – whether or not to show the down­load icon (if down­loads are enabled). Default: yes.
  • widget_show_liking– whether or not to show the Like” icon. Default: yes.
  • widget_show_playcount – whether or not to show the track play count (if pub­lic sta­tis­tics are enabled). Default: yes.
  • widget_show_sharing – whether or not to show the shar­ing icon. Default: yes.
  • widget_show_user – whether or not to show the Sound­Cloud account name above the track title in the wid­get. Default: yes.
  • widget_visual – whether or not to use the new­er visu­al” wid­get (designed for square” imple­men­ta­tions). Default: yes.
  • widget_width – width of the wid­get, expressed in pix­els or a per­cent­age. Default: 300.

With­in the loop, you have access to the fol­low­ing vari­ables, along with the stan­dard Expres­sio­nEngine {count} and {total_results} vari­ables, the {if no_results} con­di­tion­al, and the {pagination} vari­able pair:

  • {soundcloud_artwork_url_badge} — URL to the track image at 47px x 47px
  • {soundcloud_artwork_url_crop} — URL to the track image at 400px x 400px
  • {soundcloud_artwork_url_large} — URL to the track image at 100px x 100px
  • {soundcloud_artwork_url_mini} — URL to the track image at 16px x 16px
  • {soundcloud_artwork_url_small} — URL to the track image at 32px x 32px
  • {soundcloud_artwork_url_t300x300} — URL to the track image at 300px x 300px
  • {soundcloud_artwork_url_t500x500} — URL to the track image at 500px x 500px
  • {soundcloud_artwork_url_t67x67} — URL to the track image at 67px x 67px
  • {soundcloud_artwork_url_tiny} — URL to the track image at 20px x 20px
  • {soundcloud_bpm} — beats per minute
  • {soundcloud_comment_count} — num­ber of comments
  • {soundcloud_commentable} — true if com­ment­ing is enabled on the track
  • {soundcloud_created_at} — time­stamp of when the track was uploaded (accepts the stan­dard format parameter)
  • {soundcloud_description} — track description
  • {soundcloud_download_count} — num­ber of times the track has been downloaded
  • {soundcloud_download_url} — down­load link for the track
  • {soundcloud_downloadable} — true if down­loads are enabled for the track
  • {soundcloud_duration} — dura­tion in milliseconds
  • {soundcloud_duration_formatted} — dura­tion for­mat­ted as HH:MM:SS
  • {soundcloud_embeddable_by} — who is allowed to embed this track (“all” or none”)
  • {soundcloud_favoritings_count} — num­ber of times the track has been favorited
  • {soundcloud_genre} — genre for this track
  • {soundcloud_id} — Sound­Cloud inter­nal ID of this track
  • {soundcloud_isrc} — ISRC for this track
  • {soundcloud_key_signature} — key sig­na­ture of the track
  • {soundcloud_label_id} — Sound­Cloud user ID for the asso­ci­at­ed label account
  • {soundcloud_label_name} — Sound­Cloud account name for the asso­ci­at­ed label account
  • {soundcloud_license} — cre­ative com­mons license for the track
  • {soundcloud_original_content_size} — file size in bytes
  • {soundcloud_original_content_size_formatted} — file size for­mat­ted in megabytes
  • {soundcloud_original_format} — file for­mat of the orig­i­nal uploaded track
  • {soundcloud_permalink} — Sound­Cloud URL title for the track
  • {soundcloud_permalink_url} — URL to view the track on SoundCloud
  • {soundcloud_playback_count} — num­ber of times the track has been played
  • {soundcloud_purchase_url} — exter­nal pur­chase URL
  • {soundcloud_release} — release number
  • {soundcloud_release_day} — release day
  • {soundcloud_release_month} — release month
  • {soundcloud_release_year} — release year
  • {soundcloud_stream_url} — URL to the 128kbps MP3 stream for the track
  • {soundcloud_streamable} — true if the track is streamable
  • {soundcloud_tag_list} — space-sep­a­rat­ed list of tags
  • {soundcloud_title} — title of the track
  • {soundcloud_track_type} — track type
  • {soundcloud_uri} — API resource URL for the track
  • {soundcloud_user_avatar_url} — URL to the track own­er’s avatar image
  • {soundcloud_user_id} — track own­er’s Sound­Cloud user ID
  • {soundcloud_user_permalink} — track own­er’s Sound­Cloud URL title
  • {soundcloud_user_permalink_url} — URL to view the track own­er on SoundCloud
  • {soundcloud_user_uri} — API resource URL for the track­’s owner
  • {soundcloud_user_username} — track own­er’s username
  • {soundcloud_video_url} — URL to the video for this track
  • {soundcloud_waveform_url} — URL to the wave­form image for this track
  • {soundcloud_widget_html} — HTML embed code for this track­’s Sound­Cloud play­er widget

If you have request­ed to include com­ments, you also have access to the {soundcloud_comments} tag pair. With­in the tag pair, you have access to the fol­low­ing variables:

  • {soundcloud_comment_body} — text of the comment
  • {soundcloud_comment_created_at} — time­stamp of when the com­ments was cre­at­ed (accepts the stan­dard format parameter)
  • {soundcloud_comment_count} — the posi­tion of this com­ment with­in the tag pair
  • {soundcloud_comment_id} — ID of the comment
  • {soundcloud_comment_timestamp} — the posi­tion (in mil­lisec­onds) with­in the track where the com­ment was left
  • {soundcloud_comment_total_results} — the total num­ber of comments
  • {soundcloud_comment_uri} — API resource URL of the comment
  • {soundcloud_comment_user_avatar_url} — URL to the com­menter’s avatar image
  • {soundcloud_comment_user_id} — com­menter’s Sound­Cloud user ID
  • {soundcloud_comment_user_permalink} — com­menter’s Sound­Cloud URL title
  • {soundcloud_comment_user_permalink_url} — URL to view the com­menter on SoundCloud
  • {soundcloud_comment_user_uri} — API resource URL for the commenter
  • {soundcloud_comment_user_username} — com­menter’s username

Example:

{exp:soundclouded:tracks user="democracynow" include_comments="yes" limit="10"}
{if count == 1}<ul>{/if}
    <li>
        <h3><a href="{soundcloud_permalink_url}">{soundcloud_title}</a></h3>
        <p><em>Posted on {soundcloud_created_at format="%F %j%S, %Y"} ({soundcloud_duration_formatted}, {soundcloud_original_content_size_formatted})</em></p>
        <p>{soundcloud_description}</p>
        {soundcloud_widget_html}
        {soundcloud_comments}
        {if soundcloud_comment_count == 1}<ol>{/if}
            <li><a href="{soundcloud_comment_user_permalink_url}">{soundcloud_comment_user_username}</a>: {soundcloud_comment_body}</li>
        {if soundcloud_comment_count == soundcloud_comment_total_results}</ol>{/if}
        {/soundcloud_comments}
    </li>
{if count == total_results}</ul>{/if}
{paginate}
    <p>{pagination_links}</p>
{/paginate}
{if no_results}
    <p>Sorry, no tracks to display.</p>
{/if}
{/exp:soundclouded:tracks}
{exp:soundclouded:favorites}

This tag accepts all of the same para­me­ters, and returns all of the same vari­ables as the tracks tag, but will return the user’s favourite tracks, rather than the tracks they them­selves created.

{exp:soundclouded:playlists}

This tag accepts all of the same para­me­ters, and returns all of the same vari­ables as the tracks tag, but will return the user’s playlists, rather than the user’s tracks. This tag also returns a few addi­tion­al variables:

  • {soundcloud_ean} — EAN iden­ti­fi­er for the playlist
  • {soundcloud_playlist_type} — playlist type
{exp:soundclouded:track}

This tag dis­plays a sin­gle track based on its track ID or URL. It accepts all of the same para­me­ters, and returns all of the same vari­ables as the tracks tag, but rather than spec­i­fy­ing a user, you spec­i­fy a track.

  • track — the ID of, or com­plete URL of, a Sound­Cloud track
{exp:soundclouded:playlist}

This tag dis­plays a sin­gle playlist based on its playlist ID or URL. It accepts all of the same para­me­ters, and returns all of the same vari­ables as the tracks tag, but rather than spec­i­fy­ing a user, you spec­i­fy a playlist.

  • playlist — the ID of, or com­plete URL of, a Sound­Cloud playlist

Caching

Since the field­type and mod­ule tags both inter­act with Sound­Cloud’s remote API, it’s advis­able to employ some man­ner of local caching to avoid exces­sive serv­er requests. At the most basic, we sug­gest employ­ing Expres­sio­nEngine’s native tag caching — or you may want to look at a more advanced solu­tion such as CE Cache.

Support

Vis­it the offi­cial sup­port forums on devot:ee.

Changelog

  • 1.1.1 (March 25th, 2021)
    • Fixed API request error
    • Fixed playlist tag

Browse more software