Amphibian

SoundClouded

For ExpressionEngine 4+, ExpressionEngine 3, ExpressionEngine 2 • Current Version: 1.1.0

Purchase on devot:ee for $19

SoundClouded is a module and fieldtype for ExpressionEngine® which gives you full access to the SoundCloud API for selecting and displaying tracks, favourites, or playlists from any SoundCloud account. Embed player widgets with zero effort and many customizable options, or use the full suite of included variables to show only select data about your sounds, and even build your own audio player.

Using the fieldtype, setup a channel, Grid, Matrix, or Low Variables field to display a menu of tracks, favourites, or playlists from any SoundCloud user you specify. Or use the module’s template tags to loop through all available tracks, favourites or playlists from any SoundCloud user you specify, like channel entries. You can also fetch complete data for a specific track or playlist using only its URL.

Requirements

  • ExpressionEngine 2.8.0 or greater
  • cURL PHP extension

Documentation

Installation

Upload the included soundclouded folder to your /system/expressionengine/third_party/ directory, then activate the module and fieldtype from the Add-Ons → Modules menu or the Add-Ons → Fieldtypes menu.

Fieldtype

The SoundClouded fieldtype accepts three settings:

  • the type of item you want to choose from in your field (tracks, favourites, or playlists)
  • the SoundCloud Username from which you’d like to display said items
  • the number of items you’d like to display in the field’s dropdown menu (maximum is 8000, though many servers will timeout before fetching that many items from the API)

Note that private sounds are not returned via the public API, so only public sounds will be displayed.

The fieldtype is also compatible with Grid, Matrix, and Low Variables.

Fieldtype tag pair

The SoundClouded fieldtype tag pair accepts all the same parameters, and contains all the same variables, as the module template tags, with the exception of the count, total_results, and pagination tags, as the fieldtype will only ever return a single track or playlist.

Template Tags

{exp:soundclouded:tracks}

This tag pair outputs SoundCloud tracks based on the parameters provided to it. It has several parameters:

  • user(required) the username of the SoundCloud account you wish to get retrieve tracks from.
  • include_comments – whether or not to fetch any comments associated with each track. Default: no.
  • limit – the number of tracks to return per-page. Default: 50.
  • paginate – where to place the pagination markup. Can be top, bottom, or both.

The following parameters apply only to the widget embed code - if you won’t be using the player widget, you can ignore these:

  • widget_auto_play – whether or not the widget should automatically play when loaded. Default: no.
  • widget_class – class name to apply to the widget iframe.
  • widget_color – 6-character hex code to use as the highlight colour in the widget (has no effect when using the “visual” widget).
  • widget_dark_mode – whether or not the widget should use light colours on a transparent background (will only take effect if your widget is exactly 20 pixels high). Default: no.
  • widget_height – height of the widget, expressed in pixels or a percentage. Default: 300.
  • widget_hide_related – whether or not to show related tracks in the widget when paused or completed (visual widget only). Default: no.
  • widget_show_artwork – whether or not to show the track artwork (has no effect when using the “visual” widget). 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 comments in the widget waveform. Default: yes.
  • widget_show_download – whether or not to show the download icon (if downloads 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 public statistics are enabled). Default: yes.
  • widget_show_sharing – whether or not to show the sharing icon. Default: yes.
  • widget_show_user – whether or not to show the SoundCloud account name above the track title in the widget. Default: yes.
  • widget_visual – whether or not to use the newer “visual” widget (designed for “square” implementations). Default: yes.
  • widget_width – width of the widget, expressed in pixels or a percentage. Default: 300.

Within the loop, you have access to the following variables, along with the standard ExpressionEngine {count} and {total_results} variables, the {if no_results} conditional, and the {pagination} variable 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} - number of comments
  • {soundcloud_commentable} - true if commenting is enabled on the track
  • {soundcloud_created_at} - timestamp of when the track was uploaded (accepts the standard format parameter)
  • {soundcloud_description} - track description
  • {soundcloud_download_count} - number of times the track has been downloaded
  • {soundcloud_download_url} - download link for the track
  • {soundcloud_downloadable} - true if downloads are enabled for the track
  • {soundcloud_duration} - duration in milliseconds
  • {soundcloud_duration_formatted} - duration formatted as HH:MM:SS
  • {soundcloud_embeddable_by} - who is allowed to embed this track (“all” or “none”)
  • {soundcloud_favoritings_count} - number of times the track has been favorited
  • {soundcloud_genre} - genre for this track
  • {soundcloud_id} - SoundCloud internal ID of this track
  • {soundcloud_isrc} - ISRC for this track
  • {soundcloud_key_signature} - key signature of the track
  • {soundcloud_label_id} - SoundCloud user ID for the associated label account
  • {soundcloud_label_name} - SoundCloud account name for the associated label account
  • {soundcloud_license} - creative commons license for the track
  • {soundcloud_original_content_size} - file size in bytes
  • {soundcloud_original_content_size_formatted} - file size formatted in megabytes
  • {soundcloud_original_format} - file format of the original uploaded track
  • {soundcloud_permalink} - SoundCloud URL title for the track
  • {soundcloud_permalink_url} - URL to view the track on SoundCloud
  • {soundcloud_playback_count} - number of times the track has been played
  • {soundcloud_purchase_url} - external purchase 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-separated 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 owner’s avatar image
  • {soundcloud_user_id} - track owner’s SoundCloud user ID
  • {soundcloud_user_permalink} - track owner’s SoundCloud URL title
  • {soundcloud_user_permalink_url} - URL to view the track owner on SoundCloud
  • {soundcloud_user_uri} - API resource URL for the track’s owner
  • {soundcloud_user_username} - track owner’s username
  • {soundcloud_video_url} - URL to the video for this track
  • {soundcloud_waveform_url} - URL to the waveform image for this track
  • {soundcloud_widget_html} - HTML embed code for this track’s SoundCloud player widget

If you have requested to include comments, you also have access to the {soundcloud_comments} tag pair. Within the tag pair, you have access to the following variables:

  • {soundcloud_comment_body} - text of the comment
  • {soundcloud_comment_created_at} - timestamp of when the comments was created (accepts the standard format parameter)
  • {soundcloud_comment_count} - the position of this comment within the tag pair
  • {soundcloud_comment_id} - ID of the comment
  • {soundcloud_comment_timestamp} - the position (in milliseconds) within the track where the comment was left
  • {soundcloud_comment_total_results} - the total number of comments
  • {soundcloud_comment_uri} - API resource URL of the comment
  • {soundcloud_comment_user_avatar_url} - URL to the commenter’s avatar image
  • {soundcloud_comment_user_id} - commenter’s SoundCloud user ID
  • {soundcloud_comment_user_permalink} - commenter’s SoundCloud URL title
  • {soundcloud_comment_user_permalink_url} - URL to view the commenter on SoundCloud
  • {soundcloud_comment_user_uri} - API resource URL for the commenter
  • {soundcloud_comment_user_username} - commenter’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 parameters, and returns all of the same variables as the tracks tag, but will return the user’s favourite tracks, rather than the tracks they themselves created.

{exp:soundclouded:playlists}

This tag accepts all of the same parameters, and returns all of the same variables as the tracks tag, but will return the user’s playlists, rather than the user’s tracks. This tag also returns a few additional variables:

  • {soundcloud_ean} - EAN identifier for the playlist
  • {soundcloud_playlist_type} - playlist type
{exp:soundclouded:track}

This tag displays a single track based on its track ID or URL. It accepts all of the same parameters, and returns all of the same variables as the tracks tag, but rather than specifying a user, you specify a track.

  • track - the ID of, or complete URL of, a SoundCloud track
{exp:soundclouded:playlist}

This tag displays a single playlist based on its playlist ID or URL. It accepts all of the same parameters, and returns all of the same variables as the tracks tag, but rather than specifying a user, you specify a playlist.

  • playlist - the ID of, or complete URL of, a SoundCloud playlist

Caching

Since the fieldtype and module tags both interact with SoundCloud’s remote API, it’s advisable to employ some manner of local caching to avoid excessive server requests. At the most basic, we suggest employing ExpressionEngine’s native tag caching - or you may want to look at a more advanced solution such as CE Cache.

Support

Visit the official support forums on devot:ee.

Changelog

  • 1.1.0 (January 23rd, 2018)
    • Added EE3 and EE4 compatibility
  • 1.0.1 (July 20th, 2015)
    • Improved compatibility with some servers when using cURL
    • Added new widget parameters widget_show_artwork, widget_show_buying, widget_show_download, widget_show_liking, widget_show_playcountwidget_show_sharing
  • 1.0 (November 4th, 2014)
    • Initial release

Browse more software